0

Add docs on using the compile-size builder

Add instructions on how to use the compile-size builder and fix
issues. This is necessary before we block CLs in CQ that have
large increases.

Bug: 370594503
Change-Id: I035ea17a6687457dac0060ce28f843319a564687
Reviewed-on: https://chromium-review.googlesource.com/c/chromium/src/+/6246737
Commit-Queue: Erik Staab <estaab@chromium.org>
Reviewed-by: Junji Watanabe <jwata@google.com>
Reviewed-by: Hans Wennborg <hans@chromium.org>
Cr-Commit-Position: refs/heads/main@{#1418813}
This commit is contained in:
Erik Staab
2025-02-11 11:42:58 -08:00
committed by Chromium LUCI CQ
parent ca3020b9eb
commit 5e847c6565
3 changed files with 155 additions and 0 deletions

@ -0,0 +1,155 @@
# `compile-size` Builder
[TOC]
## About
The `compile-size` trybot measures and prevents unexpected growth in the size of
the C++ compiler input size, which closely [correlates][Design Doc] with time
spent in the build.
## Overview
This builder does the following:
1. With the CL and without the CL applied:
1. Builds `chrome` on Linux
2. Queries siso for build deps and commands
3. Generates a compile size report broken down by TU (translation unit)
2. Compares the two reports and writes a diff report with a summary and TU
deltas
3. If a size increase threshold is exceeded and there is no override then fail
the build
## What to do if the check fails?
1. [Inspect the report](#inspect-the-report)
2. Iterate on a fix
1. Run [locally](#run-a-local-compile_size-check) to collect a baseline (or
skip this to iterate remotely)
2. If applicable, remove transitive includes by using [forward declarations](
#forward-declarations)
3. If stuck, ask for [help](#get-help)
1. If still stuck, [override](#skip-the-check) the builder
3. Confirm results reproduce [remotely](#run-remotely)
### Inspect the report
1. On the `compile-size` builder's overview or infra page look for the summary
and the link to the `compile_size_deltas.txt` report.
![alt text](compile_size_steps.png "Screenshot of the builder overview page
with boxes highlighting the link to the diff report under 'Write size results' >
'compile_size_deltas.txt' file and the total delta summary under
'Trybot Results'.")
2. The report shows translation units with the largest increases. These can
give clues about the source of the increase. For example, when many TUs
show a similar increase in size, it could mean that a header was added to
be transitively included in all of those TUs.
![alt text](compile_size_diff_report.png "Screenshot of the compile size diff
report showing the same summary from the first screenshot on the top with the
list of translation units with the largest deltas below it.")
### Run a local compile-size check
If you want to check TU sizes locally to iterate faster, do the following:
```bash
# Set up a new build directory with the builder's GN args
tools/mb/mb gen -m tryserver.chromium.linux -b compile-size out/compile_size
# Build the `chrome` target
autoninja -C out/compile_size chrome
# Collect the size info
siso query commands -C out/compile_size chrome > /tmp/commands.txt
siso query deps -C out/compile_size > /tmp/deps.txt
tools/clang/scripts/compiler_inputs_size.py out/compile_size \
/tmp/commands.txt /tmp/deps.txt > /tmp/report.txt
```
The report will contain lines with compile sizes in bytes per TU, like
```
apps/app_lifetime_monitor.cc 9,034,754
apps/app_lifetime_monitor_factory.cc 5,863,660
apps/app_restore_service.cc 9,198,130
```
As you make changes, you can re-build, collect size info, and generate reports
to see how the per-TU numbers change. Two reports can be diffed with
[compiler_inputs_size_diff.py].
```
tools/clang/scripts/compiler_inputs_size_diff.py /tmp/report-old.txt \
/tmp/report-new.txt > /tmp/diff-report.txt
```
### Run remotely
Once done iterating on a fix locally (or if you skipped local iterations), you
can upload a new patchset or CL and trigger the `compile-size` builder to get
a new result and report.
### How to reduce your compiler input size
#### Forward Declarations
A common source of compiler input size growth is adding a header to another
widely included header. This can result in the added header getting compiled
an additional thousands or tens of thousands of times.
Chromium style prefers [forward declarations](
/styleguide/c++/c++.md#forward-declarations-vs_includes) over includes when a
full definition isn't required. For advice on when to use forward declarations
and how to minimize code in headers see [these tips](
/styleguide/c++/c++-dos-and-donts.md#minimize-code-in-headers).
Example CLs replacing header inclusion with forward declarations resulting in
large compiler input size decreases:
* [crrev.com/c/5213226](https://crrev.com/c/5213226)
* [crrev.com/c/6170321](https://crrev.com/c/6170321)
* [crrev.com/c/6073644](https://crrev.com/c/6073644)
### Get help
For help, post to build@chromium.org. They're expert build system developers.
You may also ask [#cxx](https://chromium.slack.com/archives/CGF4Y2J4W) or
[#halp](https://chromium.slack.com/archives/CGGPN5GDT) on Chromium slack.
### Skip the check
Not all checks are perfect and sometimes you want to bypass the builder (for
example, if you did your best and are unable to reduce compiler input size any
further).
Adding a `Compile-Size: $ANY_TEXT_HERE` footer to your CL description (above or
below `Bug: `) will bypass the builder assertions.
Examples:
- `Compile-Size: Size increase is unavoidable.`
- `Compile-Size: Increase is temporary.`
- `Compile-Size: See commit description.` <-- use this if longer
than one line.
***note
**Note:** Make sure there are no blank lines between `Compile-Size:` and
other footers.
***
## Builder Implementation
The analysis is done with the following scripts:
* [compiler_inputs_size.py]: Computes growth between builds,
breaking them down by TU.
* [compiler_inputs_size_diff.py]: Computes deltas from output of the
compiler_inputs_size.py script.
The GN args are in the builder's [gn-args.json] file.
## References
* [Design Doc]
* [Builder recipe](https://source.chromium.org/chromium/chromium/tools/build/+/main:recipes/recipes/compile_size_trybot.py)
* [recipe module](https://source.chromium.org/chromium/chromium/tools/build/+/main:recipes/recipe_modules/binary_size/api.py)
[compiler_inputs_size.py]: /tools/clang/scripts/compiler_inputs_size.py
[compiler_inputs_size_diff.py]: /tools/clang/scripts/compiler_inputs_size_diff.py
[Design Doc]: https://docs.google.com/document/d/1mb4XadoSqaqNZivcKpvMVfXZVXR41uP0wPC79GtDYr8/edit
[gn-args.json]: /infra/config/generated/builders/try/compile-size/gn-args.json

Binary file not shown.

After

(image error) Size: 90 KiB

Binary file not shown.

After

(image error) Size: 45 KiB