src/doc/unstable-book/src/compiler-flags/source-based-code-coverage.md

   1 # `source-based-code-coverage`
   2
   3 The feature request for this feature is: [#34701]
   4
   5 The Major Change Proposal (MCP) for this feature is: [#278](https://github.com/rust-lang/compiler-team/issues/278)
   6
   7 ------------------------
   8
   9 ## Introduction
  10
  11 The Rust compiler includes two code coverage implementations:
  12
  13 * A GCC-compatible, gcov-based coverage implementation, enabled with [`-Zprofile`](profile.md), which operates on DebugInfo.
  14 * A source-based code coverage implementation, enabled with `-Zinstrument-coverage`, which uses LLVM's native coverage instrumentation to generate very precise coverage data.
  15
  16 This document describes how to enable and use the LLVM instrumentation-based coverage, via the `-Zinstrument-coverage` compiler flag.
  17
  18 ## How it works
  19
  20 When `-Zinstrument-coverage` is enabled, the Rust compiler enhances rust-based libraries and binaries by:
  21
  22 * Automatically injecting calls to an LLVM intrinsic ([`llvm.instrprof.increment`]), at functions and branches in compiled code, to increment counters when conditional sections of code are executed.
  23 * Embedding additional information in the data section of each library and binary (using the [LLVM Code Coverage Mapping Format]), to define the code regions (start and end positions in the source code) being counted.
  24
  25 When running a coverage-instrumented program, the counter values are written to a `profraw` file at program termination. LLVM bundles tools that read the counter results, combine those results with the coverage map (embedded in the program binary), and generate coverage reports in multiple formats.
  26
  27 ## Enable coverage profiling in the Rust compiler
  28
  29 Rust's source-based code coverage requires the Rust "profiler runtime". Without it, compiling with `-Zinstrument-coverage` generates an error that the profiler runtime is missing.
  30
  31 The Rust `nightly` distribution channel should include the profiler runtime, by default.
  32
  33 *IMPORTANT:* If you are building the Rust compiler from the source distribution, the profiler runtime is *not* enabled in the default `config.toml.example`, and may not be enabled in your `config.toml`. Edit the `config.toml` file, and find the `profiler` feature entry. Uncomment it and set it to `true`:
  34
  35 ```toml
  36 # Build the profiler runtime (required when compiling with options that depend
  37 # on this runtime, such as `-C profile-generate` or `-Z instrument-coverage`).
  38 profiler = true
  39 ```
  40
  41 Then rebuild the Rust compiler (see [rustc-dev-guide-how-to-build-and-run]).
  42
  43 ### Building the demangler
  44
  45 LLVM coverage reporting tools generate results that can include function names and other symbol references, and the raw coverage results report symbols using the compiler's "mangled" version of the symbol names, which can be difficult to interpret. To work around this issue, LLVM coverage tools also support a user-specified symbol name demangler.
  46
  47 One option for a Rust demangler is [`rustfilt`](https://crates.io/crates/rustfilt), which can be installed with:
  48
  49 ```shell
  50 cargo install rustfilt
  51 ```
  52
  53 Another option, if you are building from the Rust compiler source distribution, is to use the `rust-demangler` tool included in the Rust source distribution, which can be built with:
  54
  55 ```shell
  56 $ ./x.py build rust-demangler
  57 ```
  58
  59 ## Compiling with coverage enabled
  60
  61 Set the `-Zinstrument-coverage` compiler flag in order to enable LLVM source-based code coverage profiling.
  62
  63 With `cargo`, you can instrument your program binary *and* dependencies at the same time.
  64
  65 For example (if your project's Cargo.toml builds a binary by default):
  66
  67 ```shell
  68 $ cd your-project
  69 $ cargo clean
  70 $ RUSTFLAGS="-Zinstrument-coverage" cargo build
  71 ```
  72
  73 If `cargo` is not configured to use your `profiler`-enabled version of `rustc`, set the path explicitly via the `RUSTC` environment variable. Here is another example, using a `stage1` build of `rustc` to compile an `example` binary (from the [`json5format`](https://crates.io/crates/json5format) crate):
  74
  75 ```shell
  76 $ RUSTC=$HOME/rust/build/x86_64-unknown-linux-gnu/stage1/bin/rustc \
  77     RUSTFLAGS="-Zinstrument-coverage" \
  78     cargo build --example formatjson5
  79 ```
  80
  81 ## Running the instrumented binary to generate raw coverage profiling data
  82
  83 In the previous example, `cargo` generated the coverage-instrumented binary `formatjson5`:
  84
  85 ```shell
  86 $ echo "{some: 'thing'}" | target/debug/examples/formatjson5 -
  87 ```
  88 ```json5
  89 {
  90     some: 'thing',
  91 }
  92 ```
  93
  94 After running this program, a new file, `default.profraw`, should be in the current working directory. It's often preferable to set a specific file name or path. You can change the output file using the environment variable `LLVM_PROFILE_FILE`:
  95
  96
  97 ```shell
  98 $ echo "{some: 'thing'}" \
  99     | LLVM_PROFILE_FILE="formatjson5.profraw" target/debug/examples/formatjson5 -
 100 ...
 101 $ ls formatjson5.profraw
 102 formatjson5.profraw
 103 ```
 104
 105 If `LLVM_PROFILE_FILE` contains a path to a non-existent directory, the missing directory structure will be created. Additionally, the following special pattern strings are rewritten:
 106
 107 * `%p` - The process ID.
 108 * `%h` - The hostname of the machine running the program.
 109 * `%t` - The value of the TMPDIR environment variable.
 110 * `%Nm` - the instrumented binary’s signature: The runtime creates a pool of N raw profiles, 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. `N` must be between `1` and `9`, and defaults to `1` if omitted (with simply `%m`).
 111 * `%c` - Does not add anything to the filename, but enables a mode (on some platforms, including Darwin) 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.
 112
 113 ## Creating coverage reports
 114
 115 LLVM's tools to process coverage data and coverage maps have some version dependencies. If you encounter a version mismatch, try updating your LLVM tools.
 116
 117 If you are building the Rust compiler from source, you can optionally use the bundled LLVM tools, built from source. Those tool binaries can typically be found in your build platform directory at something like: `rust/build/x86_64-unknown-linux-gnu/llvm/bin/llvm-*`. (Look for `llvm-profdata` and `llvm-cov`.)
 118
 119 Raw profiles have to be indexed before they can be used to generate coverage reports. This is done using [`llvm-profdata merge`] (which can combine multiple raw profiles and index them at the same time):
 120
 121 ```shell
 122 $ llvm-profdata merge -sparse formatjson5.profraw -o formatjson5.profdata
 123 ```
 124
 125 Finally, the `.profdata` file is used, in combination with the coverage map (from the program binary) to generate coverage reports using [`llvm-cov report`]--for a coverage summaries--and [`llvm-cov show`]--to see detailed coverage of lines and regions (character ranges), overlaid on the original source code.
 126
 127 These commands have several display and filtering options. For example:
 128
 129 ```shell
 130 $ llvm-cov show -Xdemangler=rustfilt target/debug/examples/formatjson5 \
 131     -instr-profile=formatjson5.profdata \
 132     -show-line-counts-or-regions \
 133     -show-instantiations \
 134     -name=add_quoted_string
 135 ```
 136
 137 <img alt="Screenshot of sample `llvm-cov show` result, for function add_quoted_string" src="img/llvm-cov-show-01.png" class="center"/>
 138 <br/>
 139 <br/>
 140
 141 Some of the more notable options in this example include:
 142
 143 * `--Xdemangler=rustfilt` - the command name or path used to demangle Rust symbols (`rustfilt` in the example, but this could also be a path to the `rust-demangler` tool)
 144 * `target/debug/examples/formatjson5` - the instrumented binary (from which to extract the coverage map)
 145 * `--instr-profile=<path-to-file>.profdata` - the location of the `.profdata` file created by `llvm-profdata merge` (from the `.profraw` file generated by the instrumented binary)
 146 * `--name=<exact-function-name>` - to show coverage for a specific function (or, consider using another filter option, such as `--name-regex=<pattern>`)
 147
 148 ## Interpreting reports
 149
 150 There are four statistics tracked in a coverage summary:
 151
 152 * Function coverage is the percentage of functions that have been executed at least once. A function is considered to be executed if any of its instantiations are executed.
 153 * Instantiation coverage is the percentage of function instantiations that have been executed at least once. Generic functions and functions generated from macros are two kinds of functions that may have multiple instantiations.
 154 * Line coverage is the percentage of code lines that have been executed at least once. Only executable lines within function bodies are considered to be code lines.
 155 * Region coverage is the percentage of code regions that have been executed at least once. A code region may span multiple lines: for example, in a large function body with no control flow. In other cases, a single line can contain multiple code regions: `return x || (y && z)` has countable code regions for `x` (which may resolve the expression, if `x` is `true`), `|| (y && z)` (executed only if `x` was `false`), and `return` (executed in either situation).
 156
 157 Of these four statistics, function coverage is usually the least granular while region coverage is the most granular. The project-wide totals for each statistic are listed in the summary.
 158
 159 ## Other references
 160
 161 Rust's implementation and workflow for source-based code coverage is based on the same library and tools used to implement [source-based code coverage in Clang](https://clang.llvm.org/docs/SourceBasedCodeCoverage.html). (This document is partially based on the Clang guide.)
 162
 163 [#34701]: https://github.com/rust-lang/rust/issues/34701
 164 [`llvm.instrprof.increment`]: https://llvm.org/docs/LangRef.html#llvm-instrprof-increment-intrinsic
 165 [LLVM Code Coverage Mapping Format]: https://llvm.org/docs/CoverageMappingFormat.html
 166 [rustc-dev-guide-how-to-build-and-run]: https://rustc-dev-guide.rust-lang.org/building/how-to-build-and-run.html
 167 [`llvm-profdata merge`]: https://llvm.org/docs/CommandGuide/llvm-profdata.html#profdata-merge
 168 [`llvm-cov report`]: https://llvm.org/docs/CommandGuide/llvm-cov.html#llvm-cov-report
 169 [`llvm-cov show`]: https://llvm.org/docs/CommandGuide/llvm-cov.html#llvm-cov-show