diff --git a/clang/docs/ClangCommandLineReference.rst b/clang/docs/ClangCommandLineReference.rst --- a/clang/docs/ClangCommandLineReference.rst +++ b/clang/docs/ClangCommandLineReference.rst @@ -2141,7 +2141,7 @@ .. option:: -fprofile-generate, -fno-profile-generate -Generate instrumented code to collect execution counts into default.profraw (overridden by LLVM\_PROFILE\_FILE env var) +Generate instrumented code to collect execution counts into default.profraw (overridden by LLVM\_PROFILE\_FILE env var), used for IR PGO. .. program:: clang1 .. option:: -fprofile-generate= @@ -2151,7 +2151,7 @@ .. option:: -fprofile-instr-generate, -fno-profile-instr-generate -Generate instrumented code to collect execution counts into default.profraw file (overridden by '=' form of option or LLVM\_PROFILE\_FILE env var) +Generate instrumented code to collect execution counts into default.profraw file (overridden by '=' form of option or LLVM\_PROFILE\_FILE env var), used for code coverage analysis. .. program:: clang1 .. option:: -fprofile-instr-generate= diff --git a/clang/docs/UsersManual.rst b/clang/docs/UsersManual.rst --- a/clang/docs/UsersManual.rst +++ b/clang/docs/UsersManual.rst @@ -1876,14 +1876,14 @@ Although both techniques are used for similar purposes, there are important differences between the two: -1. Profile data generated with one cannot be used by the other, and there is no - conversion tool that can convert one to the other. So, a profile generated - via ``-fprofile-instr-generate`` must be used with ``-fprofile-instr-use``. - Similarly, sampling profiles generated by external profilers must be +1. For profile guided optimizations, we recommend using IR PGO, aka using + ``-fprofile-generate`` with ``-fprofile-use``. + Sampling profiles generated by external profilers must be converted and used with ``-fprofile-sample-use``. -2. Instrumentation profile data can be used for code coverage analysis and - optimization. +2. Instrumentation profile data generated via ``-fprofile-generate`` can be used + for optimization and data generated via + ``-fprofile-instr-generate`` can be used for code coverage analysis. 3. Sampling profiles can only be used for optimization. They cannot be used for code coverage analysis. Although it would be technically possible to use @@ -2120,20 +2120,20 @@ sampling profiler. It also provides reproducible results, at least to the extent that the code behaves consistently across runs. -Here are the steps for using profile guided optimization with +Here are the steps for using profile guided optimization with LLVM IR instrumentation: 1. Build an instrumented version of the code by compiling and linking with the - ``-fprofile-instr-generate`` option. + ``-fprofile-generate`` option. .. code-block:: console - $ clang++ -O2 -fprofile-instr-generate code.cc -o code + $ clang++ -O2 -fprofile-generate code.cc -o code 2. Run the instrumented executable with inputs that reflect the typical usage. By default, the profile data will be written to a ``default.profraw`` file in the current directory. You can override that default by using option - ``-fprofile-instr-generate=`` or by setting the ``LLVM_PROFILE_FILE`` + ``-fprofile-generate=`` or by setting the ``LLVM_PROFILE_FILE`` environment variable to specify an alternate file. If non-default file name is specified by both the environment variable and the command line option, the environment variable takes precedence. The file name pattern specified @@ -2185,29 +2185,32 @@ Note that this step is necessary even when there is only one "raw" profile, since the merge operation also changes the file format. -4. Build the code again using the ``-fprofile-instr-use`` option to specify the +4. Build the code again using the ``-fprofile-use`` option to specify the collected profile data. .. code-block:: console - $ clang++ -O2 -fprofile-instr-use=code.profdata code.cc -o code + $ clang++ -O2 -fprofile-use=code.profdata code.cc -o code You can repeat step 4 as often as you like without regenerating the profile. As you make changes to your code, clang may no longer be able to use the profile data. It will warn you when this happens. Profile generation using an alternative instrumentation method can be -controlled by the GCC-compatible flags ``-fprofile-generate`` and -``-fprofile-use``. Although these flags are semantically equivalent to -their GCC counterparts, they *do not* handle GCC-compatible profiles. -They are only meant to implement GCC's semantics with respect to +controlled by ``-fprofile-instr-generate``, which is the AST-based +instrumentation used for code coverage analysis +(:doc:`source based code coverage `). + +Although the flags ``-fprofile-generate`` and ``-fprofile-use`` are semantically +equivalent to their GCC counterparts, they *do not* handle GCC-compatible +profiles. They are only meant to implement GCC's semantics with respect to profile creation and use. Flag ``-fcs-profile-generate`` also instruments programs using the same instrumentation method as ``-fprofile-generate``. .. option:: -fprofile-generate[=] The ``-fprofile-generate`` and ``-fprofile-generate=`` flags will use - an alternative instrumentation method for profile generation. When + an instrumentation method for profile generation. When given a directory name, it generates the profile file ``default_%m.profraw`` in the directory named ``dirname`` if specified. If ``dirname`` does not exist, it will be created at runtime. ``%m`` specifier @@ -2326,7 +2329,7 @@ .. code-block:: console $ echo "fun:test" > fun.list - $ clang++ -O2 -fprofile-instr-generate -fprofile-list=fun.list code.cc -o code + $ clang++ -O2 -fprofile-generate -fprofile-list=fun.list code.cc -o code The option can be specified multiple times to pass multiple files. @@ -2334,7 +2337,7 @@ $ echo "!fun:*test*" > fun.list $ echo "src:code.cc" > src.list - % clang++ -O2 -fprofile-instr-generate -fcoverage-mapping -fprofile-list=fun.list -fprofile-list=code.list code.cc -o code + % clang++ -O2 -fprofile-generate -fcoverage-mapping -fprofile-list=fun.list -fprofile-list=code.list code.cc -o code To filter individual functions or entire source files using ``fun:`` or ``src:`` respectively. To exclude a function or a source file, use @@ -3870,7 +3873,7 @@ - Address Sanitizer (ASan): ``-fsanitize=address`` - Undefined Behavior Sanitizer (UBSan): ``-fsanitize=undefined`` - Code coverage: ``-fprofile-instr-generate -fcoverage-mapping`` -- Profile Guided Optimization (PGO): ``-fprofile-instr-generate`` +- Profile Guided Optimization (PGO): ``-fprofile-generate`` - Certain math operations (int128 division) require the builtins library In order to use these features, the user must link the right runtime libraries