Prominently mention profiler = true on the coverage page

Zalathar · tshepang · commit d13e85152a97 · 2023-12-30T11:58:25.000+02:00
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`.
diff --git 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
