user0/rust
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

sembr src/llvm-coverage-instrumentation.md

Browse source
This commit is contained in:
Tshepang Mbambo 2026-02-03 00:55:09 +02:00
parent faea3136bb
commit 8c322fcdb3
1 changed files with 10 additions and 12 deletions
Download patch file Download diff file Expand all files Collapse all files

22
src/doc/rustc-dev-guide/src/llvm-coverage-instrumentation.md
View file

@ -7,13 +7,13 @@ libraries and binaries with additional instructions and data, at compile time.
The coverage instrumentation injects calls to the LLVM intrinsic instruction
[`llvm.instrprof.increment`][llvm-instrprof-increment] at code branches
(based on a MIR-based control flow analysis), and LLVM converts these to
instructions that increment static counters, when executed. The LLVM coverage
instrumentation also requires a [Coverage Map] that encodes source metadata,
instructions that increment static counters, when executed.
The LLVM coverage instrumentation also requires a [Coverage Map] that encodes source metadata,
mapping counter IDs--directly and indirectly--to the file locations (with
start and end line and column).
Rust libraries, with or without coverage instrumentation, can be linked into
instrumented binaries. When the program is executed and cleanly terminates,
Rust libraries, with or without coverage instrumentation, can be linked into instrumented binaries.
When the program is executed and cleanly terminates,
LLVM libraries write the final counter values to a file (`default.profraw` or
a custom file set through environment variable `LLVM_PROFILE_FILE`).
@ -22,8 +22,7 @@ files, with corresponding Coverage Maps (from matching binaries that produced
them), and generate various reports for analysis, for example:
<img alt="Screenshot of sample `llvm-cov show` result, for function add_quoted_string"
src="img/llvm-cov-show-01.png" class="center"/>
<br/>
src="img/llvm-cov-show-01.png" class="center"/> <br/>
Detailed instructions and examples are documented in the
[rustc book][rustc-book-instrument-coverage].
@ -39,8 +38,7 @@ When working on the coverage instrumentation code, it is usually necessary to
This allows the compiler to produce instrumented binaries, and makes it possible
to run the full coverage test suite.
Enabling debug assertions in the compiler and in LLVM is recommended, but not
mandatory.
Enabling debug assertions in the compiler and in LLVM is recommended, but not mandatory.
```toml
# Similar to the "compiler" profile, but also enables debug assertions in LLVM.
@ -60,8 +58,8 @@ rust.debug-assertions = true
`-C instrument-coverage` automatically enables Rust symbol mangling `v0` (as
if the user specified `-C symbol-mangling-version=v0` option when invoking
`rustc`) to ensure consistent and reversible name mangling. This has two
important benefits:
`rustc`) to ensure consistent and reversible name mangling.
This has two important benefits:
1. LLVM coverage tools can analyze coverage over multiple runs, including some
changes to source code; so mangled names must be consistent across compilations.
@ -71,8 +69,8 @@ important benefits:
## The LLVM profiler runtime
Coverage data is only generated by running the executable Rust program. `rustc`
statically links coverage-instrumented binaries with LLVM runtime code
Coverage data is only generated by running the executable Rust program.
`rustc` statically links coverage-instrumented binaries with LLVM runtime code
([compiler-rt][compiler-rt-profile]) that implements program hooks
(such as an `exit` hook) to write the counter values to the `.profraw` file.