Skip to content

Commit

Permalink
Prominently mention profiler = true on the coverage page
Browse files Browse the repository at this point in the history
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`.
  • Loading branch information
Zalathar authored and tshepang committed Dec 30, 2023
1 parent 84ea9ec commit d13e851
Showing 1 changed file with 30 additions and 0 deletions.
30 changes: 30 additions & 0 deletions src/llvm-coverage-instrumentation.md
Original file line number Diff line number Diff line change
Expand Up @@ -34,6 +34,32 @@ Detailed instructions and examples are documented in the
[coverage map]: https://llvm.org/docs/CoverageMappingFormat.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

`-C instrument-coverage` automatically enables Rust symbol mangling `v0` (as
Expand Down Expand Up @@ -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
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
with `-C instrument-coverage` and compares the compiled program's LLVM IR to
expected LLVM IR instructions and structured data for a coverage-enabled
Expand Down

0 comments on commit d13e851

Please sign in to comment.