Text of clang.llvm.org › docs › SourceBasedCodeCoverage.html as Styx crawled it on Nov 18, 2026. The page may have changed since. Only its words are kept, without pictures or layout, and only the first part of a long page.

Open the live page

Source-based Code Coverage - Clang

Hide navigation sidebar Hide table of contents sidebar Back to top Edit this page Toggle table of contents sidebar Source-based Code Coverage # Introduction # This document explains how to use clang’s source-based code coverage feature. It’s called “source-based” because it operates on AST and preprocessor information directly. This allows it to generate very precise coverage data. Clang ships two other code coverage implementations: SanitizerCoverage - A low-overhead tool meant for use alongside the various sanitizers.

It can provide up to edge-level coverage. gcov - A GCC-compatible coverage implementation which operates on DebugInfo. This is enabled by -ftest-coverage or --coverage . From this point onwards “code coverage” will refer to the source-based kind. The code coverage workflow # The code coverage workflow consists of three main steps: Compiling with coverage enabled. Running the instrumented program. Creating coverage reports.

The next few sections work through a complete, copy-‘n-paste friendly example based on this program: % cat << EOF > foo . cc #define BAR(x) ((x) || (x)) template < typename T > void foo ( T x ) { for ( unsigned I = 0 ; I < 10 ; ++ I ) { BAR ( I ); } } int main () { foo < int > ( 0 ); foo < float > ( 0 ); return 0 ; } EOF Compiling with coverage enabled # To compile code with coverage enabled, pass -fprofile-instr-generate -fcoverage-mapping to the compiler: # Step 1 : Compile with coverage enabled. % clang++ -fprofile-instr-generate -fcoverage-mapping foo.cc -o foo Note that linking together code with and without coverage instrumentation is supported.

Uninstrumented code simply won’t be accounted for in reports. To compile code with Modified Condition/Decision Coverage (MC/DC) enabled, pass -fcoverage-mcdc in addition to the clang options specified above. MC/DC is an advanced form of code coverage most applicable to the embedded space. Running the instrumented program # The next step is to run the instrumented program. When the program exits, it will write a raw profile to the path specified by the LLVM_PROFILE_FILE environment variable.

If that variable does not exist, the profile is written to default.profraw in the current directory of the program. If LLVM_PROFILE_FILE specifies a path to a non-existent directory, the missing directory structure will be created. Additionally, the following special pattern strings are rewritten: “%p” expands out to the process ID. “%h” expands out to the hostname of the machine running the program. “%t” expands out to the value of the TMPDIR environment variable.

On Darwin, this is typically set to a temporary scratch directory. “%Nm” expands out to the instrumented binary’s signature. When this pattern is specified, the runtime creates a pool of N raw profiles which are used for on-line profile merging. The runtime takes care of selecting a raw profile from the pool, locking it, and updating it before the program exits. If N is not specified (i.e the pattern is “%m”), it’s assumed that N = 1 .

The merge pool specifier can only occur once per filename pattern. “%b” expands out to the binary ID (build ID). It can be used with “%Nm” to avoid binary signature collisions. To use it, the program should be compiled with the build ID linker option ( --build-id for GNU ld or LLD, /build-id for lld-link on Windows). Linux, Windows, and AIX are supported. “%c” expands out to nothing, but enables a mode in which profile counter updates are continuously synced to a file.

This means that if the instrumented program crashes, or is killed by a signal, perfect coverage information can still be recovered. Continuous mode does not support value profiling for PGO, and is only supported on Darwin at the moment. Support for Linux may be mostly complete but requires testing, and support for Windows may require more extensive changes: please get involved if you are interested in porting this feature. # Step 2 : Run the program. % LLVM_PROFILE_FILE = "foo.profraw" ./foo Note that continuous mode is also used on Fuchsia where it’s the only supported mode, but the implementation is different.

The Darwin and Linux implementation relies on padding and the ability to map a file over the existing memory mapping which is generally only available on POSIX systems and isn’t suitable for other platforms. On Fuchsia, we rely on the ability to relocate counters at runtime using a level of indirection. On every counter access, we add a bias to the counter address. This bias is stored in __llvm_profile_counter_bias symbol that’s provided by the profile runtime and is initially set to zero, meaning no relocation.

The runtime can map the profile into memory at arbitrary locations, and set bias to the offset between the original and the new counter location, at which point every subsequent counter access will be to the new location, which allows updating profile directly akin to the continuous mode. The advantage of this approach is that it 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 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. Note that “%p” is also a Lit token and needs to be escaped as “%%p”. % clang++ -fprofile-instr-generate -fcoverage-mapping -mllvm -runtime-counter-relocation foo.cc -o foo Creating coverage reports # Raw profiles must 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): # 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 . There are multiple different ways to render coverage reports. The simplest option is to generate a line-oriented report: # Step 3 ( b ) : Create a line-oriented coverage report. % llvm-cov show ./foo -instr-profile = foo.profdata This report includes a summary view as well as dedicated sub-views for templated functions and their instantiations.

For our example program, we get distinct views for foo<int>(...) and foo<float>(...) . If -show-line-counts-or-regions is enabled, llvm-cov displays sub-line region counts (even in macro expansions): 1| 20|#define BAR(x) ((x) || (x)) ^20 ^2 2| 2|template <typename T> void foo(T x) { 3| 22| for (unsigned I = 0; I < 10; ++I) { BAR(I); } ^22 ^20 ^20^20 4| 2|} ------------------ | void foo<int>(int): | 2| 1|template <typename T> void foo(T x) { | 3| 11| for (unsigned I = 0; I < 10; ++I) { BAR(I); } | ^11 ^10 ^10^10 | 4| 1|} ------------------ | void foo<float>(int): | 2| 1|template <typename T> void foo(T x) { | 3| 11| for (unsigned I = 0; I < 10; ++I) { BAR(I); } | ^11 ^10 ^10^10 | 4| 1|} ------------------ If --show-branches=count and --show-expansions are also enabled, the sub-views will show detailed branch coverage information in addition to the region counts: ------------------ | void foo<float>(int): | 2| 1|template <typename T> void foo(T x) { | 3| 11| for (unsigned I = 0; I < 10; ++I) { BAR(I); } | ^11 ^10 ^10^10 | ------------------ | | | 1| 10|#define BAR(x) ((x) || (x)) | | | ^10 ^1 | | | ------------------ | | | | Branch (1:17): [True: 9, False: 1] | | | | Branch (1:24): [True: 0, False: 1] | | | ------------------ | ------------------ | | Branch (3:23): [True: 10, False: 1] | --------------

The rest of this page is on the live site.