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

instrument-coverage has been stabilized.

This commit is contained in:
Eric Huss 2022-02-20 07:09:56 -08:00 committed by Noah Lev
parent d3cc250a1c
commit 55ee2bb081
2 changed files with 9 additions and 10 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

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

@ -3,7 +3,7 @@
<!-- toc --> <!-- toc -->
`rustc` supports detailed source-based code and test coverage analysis `rustc` supports detailed source-based code and test coverage analysis
with a command line option (`-Z instrument-coverage`) that instruments Rust with a command line option (`-C instrument-coverage`) that instruments Rust
libraries and binaries with additional instructions and data, at compile time. libraries and binaries with additional instructions and data, at compile time.
The coverage instrumentation injects calls to the LLVM intrinsic instruction The coverage instrumentation injects calls to the LLVM intrinsic instruction
@ -28,16 +28,15 @@ them), and generate various reports for analysis, for example:
<br/> <br/>
Detailed instructions and examples are documented in the Detailed instructions and examples are documented in the
[Rust Unstable Book (under [Rustc Book][rustc-book-instrument-coverage].
_compiler-flags/instrument-coverage_)][unstable-book-instrument-coverage].
[llvm-instrprof-increment]: https://llvm.org/docs/LangRef.html#llvm-instrprof-increment-intrinsic [llvm-instrprof-increment]: https://llvm.org/docs/LangRef.html#llvm-instrprof-increment-intrinsic
[coverage map]: https://llvm.org/docs/CoverageMappingFormat.html [coverage map]: https://llvm.org/docs/CoverageMappingFormat.html
[unstable-book-instrument-coverage]: https://doc.rust-lang.org/nightly/unstable-book/compiler-flags/instrument-coverage.html [rustc-book-instrument-coverage]: https://doc.rust-lang.org/nightly/rustc/instrument-coverage.html
## Rust symbol mangling ## Rust symbol mangling
`-Z instrument-coverage` automatically enables Rust symbol mangling `v0` (as `-C instrument-coverage` automatically enables Rust symbol mangling `v0` (as
if the user specified `-C symbol-mangling-version=v0` option when invoking if the user specified `-C symbol-mangling-version=v0` option when invoking
`rustc`) to ensure consistent and reversible name mangling. This has two `rustc`) to ensure consistent and reversible name mangling. This has two
important benefits: important benefits:
@ -62,7 +61,7 @@ In the `rustc` source tree, `library/profiler_builtins` bundles the LLVM
`profiler_builtins` library is only included when `profiler = true` is set `profiler_builtins` library is only included when `profiler = true` is set
in `rustc`'s `config.toml`.) in `rustc`'s `config.toml`.)
When compiling with `-Z instrument-coverage`, When compiling with `-C instrument-coverage`,
[`CrateLoader::postprocess()`][crate-loader-postprocess] dynamically loads the [`CrateLoader::postprocess()`][crate-loader-postprocess] dynamically loads the
`profiler_builtins` library by calling `inject_profiler_runtime()`. `profiler_builtins` library by calling `inject_profiler_runtime()`.
@ -287,7 +286,7 @@ instrumented) in the [`coverage`][coverage-test-samples] directory, and the
actual tests and expected results in [`coverage-reports`]. actual tests and expected results in [`coverage-reports`].
Finally, the [`coverage-llvmir`] test compares compiles a simple Rust program Finally, the [`coverage-llvmir`] test compares compiles a simple Rust program
with `-Z 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
program, including various checks for Coverage Map-related metadata and the LLVM program, including various checks for Coverage Map-related metadata and the LLVM
intrinsic calls to increment the runtime counters. intrinsic calls to increment the runtime counters.
@ -424,7 +423,7 @@ theme in your development environment, you will probably want to use this
option so you can review the graphviz output without straining your vision. option so you can review the graphviz output without straining your vision.
```shell ```shell
$ rustc -Z instrument-coverage -Z dump-mir=InstrumentCoverage \ $ rustc -C instrument-coverage -Z dump-mir=InstrumentCoverage \
-Z dump-mir-graphviz some_rust_source.rs -Z dump-mir-graphviz some_rust_source.rs
``` ```
@ -497,7 +496,7 @@ An visual, interactive representation of the final `CoverageSpan`s can be
generated with the following `rustc` flags: generated with the following `rustc` flags:
```shell ```shell
$ rustc -Z instrument-coverage -Z dump-mir=InstrumentCoverage \ $ rustc -C instrument-coverage -Z dump-mir=InstrumentCoverage \
-Z dump-mir-spanview some_rust_source.rs -Z dump-mir-spanview some_rust_source.rs
``` ```

2
src/profile-guided-optimization.md
View File

@ -49,7 +49,7 @@ workflow to see how they interact.
[^note-instrument-coverage]: Note: `rustc` now supports front-end-based coverage [^note-instrument-coverage]: Note: `rustc` now supports front-end-based coverage
instrumentation, via the experimental option instrumentation, via the experimental option
[`-Z instrument-coverage`](./llvm-coverage-instrumentation.md), but using these [`-C instrument-coverage`](./llvm-coverage-instrumentation.md), but using these
coverage results for PGO has not been attempted at this time. coverage results for PGO has not been attempted at this time.
### Overall Workflow ### Overall Workflow