How does profile-guided optimization with GCC's -fprofile-generate and -fprofile-use work, and what makes its training run trustworthy?
answer
- instrument, train, rebuild
- .gcda counts per object
- same flags both builds
- representative workload
- atomic counters for threads
basics
~20 sBuild with -fprofile-generate, run a representative workload so the program writes .gcda count files, then rebuild with -fprofile-use. GCC then knows hot branches and loops, but the result is only as good as the training run.
solid answer
~40 sPGO is a three-step build. First compile **and link** with `-fprofile-generate`, which adds counters (`-fprofile-arcs`, `-fprofile-values`). Then run the instrumented program on a **representative workload**; at exit it writes a `.gcda` file per object with branch, call and value counts. Finally rebuild from the same sources and flags with `-fprofile-use`, which reads the counts and enables `-fbranch-probabilities`, `-funroll-loops`, `-fpeel-loops`, `-ftracer`, value profiling and the `dynamic` vectorizer cost model, so hot paths are inlined and laid out for speed while code never executed in training is optimized for size. Trust depends on the training run: it must exercise the paths production takes, multithreaded programs should use `-fprofile-update=atomic` (the driver picks `prefer-atomic` with `-pthread`), and profiles must be regenerated after source changes, since by default GCC errors on a mismatching profile and warns about missing ones.
code
bash · 6 lines# 1. instrumented build (compile and link)
g++ -O2 -fprofile-generate -fprofile-update=atomic -pthread src/*.cpp -o app_instr
# 2. training run writes .gcda files next to the objects
./app_instr --replay traces/typical-day.log
# 3. optimized build with the same flags plus the profile
g++ -O2 -fprofile-use -pthread src/*.cpp -o appgo deeper
Know the idea: build instrumented, run it, rebuild using the measured profile.
Walk through -fprofile-generate, the .gcda files and -fprofile-use, and name what the profile changes.
Make training representative, handle threads with -fprofile-update, and deal with stale or missing profiles in CI.
Decide whether PGO's pipeline cost is worth its measured gain, and own the training workload as a versioned asset.
## Why profiles help At `-O2` GCC guesses which branches are likely, which loops run long and which functions are hot, using heuristics. **Profile-guided optimization (PGO)** replaces the guesses with measurements from real runs. With them GCC can inline the calls that matter, lay out hot code contiguously, unroll loops whose trip counts are known, and specialise code for the values that actually occur. ## The three steps 1. **Instrument.** Compile and link with `-fprofile-generate`. The manual says you must use it both when compiling and when linking. It enables `-fprofile-arcs` and `-fprofile-values`, plus `-finline-functions` and `-fipa-bit-cp`. 2. **Train.** Run the instrumented program on a representative workload. When it exits, it writes a `auxname.gcda` file per object with the counts: for `-o dir/foo.o` the file is `dir/foo.gcda`. `-fprofile-dir=path` collects them elsewhere. 3. **Optimize.** Rebuild from the same sources with `-fprofile-use`, which reads the counts and enables optimizations that mostly pay off only with profile feedback. | `-fprofile-use` enables | Effect | |---|---| | `-fbranch-probabilities` | real branch frequencies for layout and decisions | | `-funroll-loops`, `-fpeel-loops` | unrolling where trip counts justify it | | `-ftracer` | duplicating hot paths to remove joins | | `-fprofile-values`, `-fvpt` | specialising for observed values | | `-fvect-cost-model=dynamic` | more aggressive vectorization in hot loops | | `-fprofile-reorder-functions` | grouping hot functions together | ## What makes the training trustworthy - **Representative input.** PGO optimizes what the training run did. Code never executed during training is, by default, optimized **for size rather than speed**. If production takes a path the training skipped, that path gets slower than without PGO. `-fprofile-partial-training` tells GCC to ignore the profile for functions not executed in training and optimize them normally, at the cost of bigger code. - **Thread-safe counters.** In a multithreaded program, concurrent counter updates can corrupt the profile. `-fprofile-update=atomic` makes the updates thread-safe; the driver selects `prefer-atomic` automatically when `-pthread` is on the command line. Threads that are never joined can still corrupt the file. - **Fresh profiles.** By default GCC emits an **error** when a profile does not match the source; `-Wno-error=coverage-mismatch` turns it into a warning at the price of poorer code. It also warns, through `-Wmissing-profile`, when a function or file has no profile data because it was added after training. - **Same flags.** The instrumented and optimized builds should use the same options, apart from the profile flags, so the profile maps cleanly onto the code. ## Fitting it into a release pipeline 1. Build the instrumented binary in CI. 2. Run a scripted, versioned training workload that mirrors production traffic, such as a replayed request log, a benchmark scene for a game or a set of representative files for a codec. 3. Archive the `.gcda` files with the commit they belong to. 4. Build the release with `-fprofile-use`, usually together with LTO, which the linking material covers. 5. Benchmark the result against the plain `-O2` build and keep PGO only if it wins. ## Common mistakes - **Training on the test suite.** Unit tests exercise error paths and edge cases far more than production does, so the profile marks the wrong code hot. - **Forgetting the link flag.** `-fprofile-generate` on the compile line but not the link line leaves the profiling runtime out of the link, which then typically fails with undefined references to its functions. - **Training in a different directory layout.** `.gcda` files are named after the objects; a training run whose objects were built elsewhere leaves files the optimized build cannot find, and `-Wmissing-profile` reports missing profiles. `-fprofile-dir` gives them a fixed home. - **Mixing flags.** Different `-O` levels or macros between the two builds change the control flow, and the profile no longer matches. - **Assuming the gain lasts.** As the code and its traffic change, an old profile slowly optimizes yesterday's program. Retrain on a schedule. ## An alternative: sampling profiles `-fauto-profile` uses **AutoFDO** profiles collected with a sampling profiler from an ordinary, uninstrumented optimized binary running in production, converted into GCC's format. It avoids the slow instrumented build and uses real traffic, at the cost of less precise counts and extra tooling.
- What happens to code that never ran during the PGO training run?With `-fprofile-use`, functions and paths not executed in training are optimized for size rather than speed, on the assumption that they are cold. If production does run them, they can get slower. `-fprofile-partial-training` makes GCC ignore the profile for such functions and optimize them normally.
- Why does a PGO build fail after someone edits a source file without retraining?The `.gcda` data no longer matches the function's control flow, and GCC reports a coverage mismatch as an error by default. Retrain, or downgrade it with `-Wno-error=coverage-mismatch` knowing the affected code will be poorly optimized.
- -fprofile-generate is only needed at compile time, not at link time.
- Any run of the program produces a good profile.
- Profiles stay valid after the source changes.
- PGO cannot make any path slower than a plain -O2 build.
- Multithreaded programs need no special care when collecting profiles.