LLVM's supplies two tools—`llvm-profdata` and `llvm-cov`—that process coverage data and generate reports. There are several ways to find and/or install these tools, but note that the coverage mapping data generated by the Rust compiler requires LLVM version 12 or higher. (`llvm-cov --version` typically shows the tool's LLVM version number.):
-- The LLVM tools may be installed (or installable) directly to your OS (such as via `apt-get`, for Linux).
+- You can install the LLVM tools from your operating system distribution, or from your distribution of LLVM.
- If you are building the Rust compiler from source, you can optionally use the bundled LLVM tools, built from source. Those tool binaries can typically be found in your build platform directory at something like: `rust/build/x86_64-unknown-linux-gnu/llvm/bin/llvm-*`.
-- You can install compatible versions of these tools via `rustup`.
+- You can install compatible versions of these tools via the `rustup` component `llvm-tools-preview`, though this is still considered experimental. In this case, you may also find `cargo-binutils` useful as a wrapper around these tools.
-The `rustup` option is guaranteed to install a compatible version of the LLVM tools, but they can be hard to find. We recommend [`cargo-binutils`], which installs Rust-specific wrappers around these and other LLVM tools, so you can invoke them via `cargo` commands!
-
-```shell
-$ rustup component add llvm-tools-preview
-$ cargo install cargo-binutils
-$ cargo profdata -- --help # note the additional "--" preceding the tool-specific arguments
-```
-
-[`cargo-binutils`]: https://crates.io/crates/cargo-binutils
+The examples in this document show how to use the llvm tools directly.
## Creating coverage reports
-Raw profiles have to be indexed before they can be used to generate coverage reports. This is done using [`llvm-profdata merge`] (or `cargo profdata -- merge`), which can combine multiple raw profiles and index them at the same time:
+Raw profiles have to be indexed before they can be used to generate coverage reports. This is done using [`llvm-profdata merge`], which can combine multiple raw profiles and index them at the same time:
```shell
$ llvm-profdata merge -sparse formatjson5.profraw -o formatjson5.profdata
```
-Finally, the `.profdata` file is used, in combination with the coverage map (from the program binary) to generate coverage reports using [`llvm-cov report`] (or `cargo cov -- report`), for a coverage summaries; and [`llvm-cov show`] (or `cargo cov -- show`), to see detailed coverage of lines and regions (character ranges) overlaid on the original source code.
+Finally, the `.profdata` file is used, in combination with the coverage map (from the program binary) to generate coverage reports using [`llvm-cov report`], for a coverage summaries; and [`llvm-cov show`], to see detailed coverage of lines and regions (character ranges) overlaid on the original source code.
These commands have several display and filtering options. For example:
You should have one or more `.profraw` files now, one for each test binary. Run the `profdata` tool to merge them:
```shell
-$ cargo profdata -- merge \
- -sparse json5format-*.profraw -o json5format.profdata
+$ llvm-profdata merge -sparse json5format-*.profraw -o json5format.profdata
```
Then run the `cov` tool, with the `profdata` file and all test binaries:
```shell
-$ cargo cov -- report \
+$ llvm-cov report \
--use-color --ignore-filename-regex='/.cargo/registry' \
--instr-profile=json5format.profdata \
--object target/debug/deps/lib-30768f9c53506dc5 \
--object target/debug/deps/json5format-fececd4653271682
-$ cargo cov -- show \
+$ llvm-cov show \
--use-color --ignore-filename-regex='/.cargo/registry' \
--instr-profile=json5format.profdata \
--object target/debug/deps/lib-30768f9c53506dc5 \
For `bash` users, one suggested way to automatically complete the `cov` command with the list of binaries is with a command like:
```bash
-$ cargo cov -- report \
+$ llvm-cov report \
$( \
for file in \
$( \
To include doc tests in the coverage results, drop the `--tests` flag, and apply the
`-C instrument-coverage` flag, and some doc-test-specific options in the
-`RUSTDOCFLAGS` environment variable. (The `cargo profdata` command does not change.)
+`RUSTDOCFLAGS` environment variable. (The `llvm-profdata` command does not change.)
```bash
$ RUSTFLAGS="-C instrument-coverage" \
RUSTDOCFLAGS="-C instrument-coverage -Z unstable-options --persist-doctests target/debug/doctestbins" \
LLVM_PROFILE_FILE="json5format-%m.profraw" \
cargo test
-$ cargo profdata -- merge \
- -sparse json5format-*.profraw -o json5format.profdata
+$ llvm-profdata merge -sparse json5format-*.profraw -o json5format.profdata
```
The `-Z unstable-options --persist-doctests` flag is required, to save the test binaries
(with their coverage maps) for `llvm-cov`.
```bash
-$ cargo cov -- report \
+$ llvm-cov report \
$( \
for file in \
$( \
--instr-profile=json5format.profdata --summary-only # and/or other options
```
-> **Note**: The differences in this `cargo cov` command, compared with the version without
-> doc tests, include:
+> **Note**: The differences in this `llvm-cov` invocation, compared with the
+> version without doc tests, include:
- The `cargo test ... --no-run` command is updated with the same environment variables
and flags used to _build_ the tests, _including_ the doc tests. (`LLVM_PROFILE_FILE`
projects / rust.git / commitdiff