59559 Explain code coverage with Lit in docs/SourceBasedCodeCoverage.rst

[FlashSheridan]

Summary

The documentation for code coverage in docs/SourceBasedCodeCoverage.rst omits a couple of crucial steps when using it with Lit. I’d suggest the following additions:
At the end of “Running the instrumented program”:

For a program such as the :doc:Lit <CommandGuide/lit> testing tool which
invokes other programs, it may be necessary to set LLVM_PROFILE_FILE for
each invocation. The pattern strings "%p" or "%Nm" may help to avoid
corruption due to concurrency.

18 lines later, after “code-block:: console”:

For an example of merging multiple profiles created by testing,
see the LLVM coverage build script https://github.com/llvm/llvm-zorg/blob/main/zorg/jenkins/jobs/jobs/llvm-coverage_.

[FlashSheridan]

clang/docs/SourceBasedCodeCoverage.rst

133

[gkistanova]

LGTM.

[FlashSheridan]

Per https://llvm.org/docs/Phabricator.html#committing-a-change, I cannot commit the patch myself.

clang/docs/SourceBasedCodeCoverage.rst

 The advantage of this approach is that doesn't require any special OS support.
 The disadvantage is the extra overhead due to additional instructions required
 for each counter access (overhead both in terms of binary size and performance)
 plus duplication of counters (i.e. one copy in the binary itself and another
 copy that's mapped into memory). This implementation can be also enabled for
 other platforms by passing the ``-runtime-counter-relocation`` option to the
 backend during compilation.
 
+For a program such as the :doc:`Lit <CommandGuide/lit>` testing tool which
+invokes other programs, it may be necessary to set ``LLVM_PROFILE_FILE`` for
+each invocation. The pattern strings "%p" or "%Nm" may help to avoid
+corruption due to concurrency.
+
 .. code-block:: console
 
     % clang++ -fprofile-instr-generate -fcoverage-mapping -mllvm -runtime-counter-relocation foo.cc -o foo
 
 Creating coverage reports
 =========================
 
 Raw profiles have to be **indexed** before they can be used to generate
 coverage reports. This is done using the "merge" tool in ``llvm-profdata``
 (which can combine multiple raw profiles and index them at the same time):
 
 .. code-block:: console
 
     # Step 3(a): Index the raw profile.
     % llvm-profdata merge -sparse foo.profraw -o foo.profdata
 
+For an example of merging multiple profiles created by testing,
+see the LLVM `coverage build script <https://github.com/llvm/llvm-zorg/blob/main/zorg/jenkins/jobs/jobs/llvm-coverage>`_.
+
 There are multiple different ways to render coverage reports. The simplest
 option is to generate a line-oriented report:
 
 .. code-block:: console
 
     # Step 3(b): Create a line-oriented coverage report.
     % llvm-cov show ./foo -instr-profile=foo.profdata