[clang] 9b06669 - [Clang][Docs] Improve -fcs-profile-generate documentation (#239616)

via cfe-commits cfe-commits at lists.llvm.org
Thu Nov 12 01:20:03 PST 2026


Author: AMullen
Date: 2026-11-12T09:19:58Z
New Revision: 9b066693658e5e6c86602a51c0ca6a828ae62b82

URL: https://github.com/llvm/llvm-project/commit/9b066693658e5e6c86602a51c0ca6a828ae62b82
DIFF: https://github.com/llvm/llvm-project/commit/9b066693658e5e6c86602a51c0ca6a828ae62b82.diff

LOG: [Clang][Docs] Improve -fcs-profile-generate documentation (#239616)

The current documentation for `-fcs-profile-generate` does not clearly
explain the additional profiling stage or the need to combine the base
and context-sensitive profiles to produce a CSPGO-optimized executable.
This PR makes these requirements clearer, and also expands on the
current example to highlight these points.

Added: 
    

Modified: 
    clang/docs/UsersManual.md

Removed: 
    


################################################################################
diff  --git a/clang/docs/UsersManual.md b/clang/docs/UsersManual.md
index 79629aab40342..6a9d976e248f0 100644
--- a/clang/docs/UsersManual.md
+++ b/clang/docs/UsersManual.md
@@ -3515,9 +3515,11 @@ better runtime performance. Frontend-based instrumentation, on the other hand,
 has better source correlation, so it should be used with source line-based
 coverage testing.
 
-The flag `-fcs-profile-generate` also instruments programs using the same
-instrumentation method as `-fprofile-generate`. However, it performs a
-post-inline late instrumentation and can produce context-sensitive profiles.
+After inlining, the `-fcs-profile-generate` option inserts additional
+instrumentation to collect context-sensitive profile information. It can be
+used without an existing profile that has been collected using `-fprofile-generate`.
+However, it is common to merge the profiles generated from each option. A worked
+example is given when discussing `-fcs-profile-generate` further.
 
 Here are the steps for using profile guided optimization with
 instrumentation:
@@ -3646,41 +3648,68 @@ To override the path and filename at compile time, use
 :::{option} -fcs-profile-generate[=<dirname>]
 
 The `-fcs-profile-generate` and `-fcs-profile-generate=` flags will use
-the same instrumentation method, and generate the same profile as in the
-`-fprofile-generate` and `-fprofile-generate=` flags. The 
diff erence is
-that the instrumentation is performed after inlining so that the resulted
-profile has a better context sensitive information. They cannot be used
-together with `-fprofile-generate` and `-fprofile-generate=` flags.
-They are typically used in conjunction with `-fprofile-use` flag.
-The profile generated by `-fcs-profile-generate` and `-fprofile-generate`
-can be merged by llvm-profdata. A use example:
+the same IR instrumentation method as the `-fprofile-generate` and
+`-fprofile-generate=` flags, but insert instrumentation after inlining. This
+collects the context-sensitive information in the profile. They cannot be used
+together with the `-fprofile-generate` and `-fprofile-generate=` flags in the
+same compiler invocation. They are typically used in conjunction with
+the `-fprofile-use` flag. The profiles generated by `-fcs-profile-generate`
+and `-fprofile-generate` can be merged by llvm-profdata to produce
+a context-sensitive PGO optimized executable. A worked example
+of this two-stage profiling workflow is described below:
+
+The first stage is to compile and run an executable with IR instrumentation to
+produce a base profile using the `-fprofile-generate` option, which is stored
+in `profiles/base/` in the example below. `llvm-profdata` is used to convert
+the raw profile data into a readable format for Clang.
 
 ```console
-$ clang++ -O2 -fprofile-generate=yyy/zzz code.cc -o code
-$ ./code
-$ llvm-profdata merge -output=code.profdata yyy/zzz/
+# General form: clang++ -O2 -fprofile-generate=<pathToBaseProfile> <source> -o <executable>
+$ clang++ -O2 -fprofile-generate=profiles/base main.cpp -o main-base
+$ ./main-base
+$ llvm-profdata merge profiles/base/ -o base.profdata
 ```
 
-The first few steps are the same as that in `-fprofile-generate`
-compilation. Then perform a second round of instrumentation.
+The converted profile, `base.profdata`, above, will be
+outputted into the current directory. At this stage, the next step is
+to produce an instrumented build of the source code with context-sensitive
+instrumentation. This can be done using the `-fcs-profile-generate` option.
+
+We still use the base profile collected using the IR instrumentation
+because it is used to guide inlining decisions, which can then be used by the
+context-sensitive instrumentation to generate a context-sensitive profile.
 
 ```console
-$ clang++ -O2 -fprofile-use=code.profdata -fcs-profile-generate=sss/ttt \
-  -o cs_code
-$ ./cs_code
-$ llvm-profdata merge -output=cs_code.profdata sss/ttt code.profdata
+# General form: clang++ -O2 -fprofile-use=<baseProfile> -fcs-profile-generate=<pathToCSProfile> <source> -o <executable>
+$ clang++ -O2 -fprofile-use=base.profdata -fcs-profile-generate=profiles/cs/ main.cpp -o main-cs
 ```
 
-The resulted `cs_code.prodata` combines `code.profdata` and the profile
-generated from binary `cs_code`. Profile `cs_code.profata` can be used by
-`-fprofile-use` compilation.
+Running this executable allows us to collect the context-sensitive
+profile information. In this example, the profile will be written
+to `profiles/cs/`.
 
 ```console
-$ clang++ -O2 -fprofile-use=cs_code.profdata
+$ ./main-cs
 ```
 
-The above command will read both profiles to the compiler at the identical
-point of instrumentations.
+When using profiles collected using both the `-fprofile-generate` and
+`-fcs-profile-generate` options, they must be merged into one profile.
+This is because they provide information for 
diff erent stages of the
+compilation pipeline. It should be noted that the combined profile
+will be written into the current directory.
+
+```console
+$ llvm-profdata merge base.profdata profiles/cs/ -o combined.profdata
+```
+
+Using this new profile, we can compile the final optimized executable
+with CSPGO optimization using the `-fprofile-use` option. The command
+below will ensure that the compilation uses the base profile before
+inlining and the context-sensitive profile after inlining.
+
+```console
+$ clang++ -O2 -fprofile-use=combined.profdata main.cpp -o main-final
+```
 :::
 
 :::{option} -fprofile-use[=<pathname>]


        


More information about the cfe-commits mailing list