From d13e85152a977cd0bcaf583cf5f49e86225697de Mon Sep 17 00:00:00 2001 From: Zalathar Date: Sat, 30 Dec 2023 13:56:22 +1100 Subject: [PATCH] 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`. --- src/llvm-coverage-instrumentation.md | 30 ++++++++++++++++++++++++++++ 1 file changed, 30 insertions(+) diff --git a/src/llvm-coverage-instrumentation.md b/src/llvm-coverage-instrumentation.md index a21254946..545b48873 100644 --- a/src/llvm-coverage-instrumentation.md +++ b/src/llvm-coverage-instrumentation.md @@ -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 @@ -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