mirror
/
rustc-dev-guide
mirror of https://github.com/rust-lang/rustc-dev-guide.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Prominently mention `profiler = true` on the coverage page 

Enabling the profiler runtime is an essential part of being able to properly
work on the coverage instrumentation code.

There's already a mention of it on this page, but it's made in passing and is
easy to miss. This patch adds a much more prominent section containing
recommended `config.toml` settings, including `profiler = true`.
This commit is contained in:
Zalathar 2023-12-30 13:56:22 +11:00 committed by Tshepang Mbambo
parent 03cf281953
commit c829322db7
1 changed files with 30 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

30
src/llvm-coverage-instrumentation.md
View File

@ -34,6 +34,32 @@ Detailed instructions and examples are documented in the
[coverage map]: https://llvm.org/docs/CoverageMappingFormat.html [coverage map]: https://llvm.org/docs/CoverageMappingFormat.html
[rustc-book-instrument-coverage]: https://doc.rust-lang.org/nightly/rustc/instrument-coverage.html [rustc-book-instrument-coverage]: https://doc.rust-lang.org/nightly/rustc/instrument-coverage.html
## Recommended `config.toml` settings
When working on the coverage instrumentation code, it is usually necessary to
**enable the profiler runtime** by setting `profiler = true` in `[build]`.
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.
```toml
# Similar to the "compiler" profile, but also enables debug assertions in LLVM.
# These assertions can detect malformed coverage mappings in some cases.
profile = "codegen"
[build]
# IMPORTANT: This tells the build system to build the LLVM profiler runtime.
# Without it, the compiler can't produce coverage-instrumented binaries,
# and many of the coverage tests will be skipped.
profiler = true
[rust]
# Enable debug assertions in the compiler.
debug-assertions = true
```
## Rust symbol mangling ## Rust symbol mangling
`-C instrument-coverage` automatically enables Rust symbol mangling `v0` (as `-C instrument-coverage` automatically enables Rust symbol mangling `v0` (as
@ -292,6 +318,10 @@ These tests compile and run a test program with coverage
instrumentation, then use LLVM tools to convert the coverage data into a instrumentation, then use LLVM tools to convert the coverage data into a
human-readable coverage report. human-readable coverage report.
> Tests in `coverage-run` mode have an implicit `// needs-profiler-support`
> directive, so they will be skipped if the profiler runtime has not been
> [enabled in `config.toml`](#recommended-configtoml-settings).
Finally, the [`coverage-llvmir`] test compiles a simple Rust program Finally, the [`coverage-llvmir`] test compiles a simple Rust program
with `-C instrument-coverage` and compares the compiled program's LLVM IR to with `-C instrument-coverage` and compares the compiled program's LLVM IR to
expected LLVM IR instructions and structured data for a coverage-enabled expected LLVM IR instructions and structured data for a coverage-enabled