minicov

This crate provides code coverage support for no_std and embedded programs.

Usage

Note: This crate requires a recent nightly compiler (2020-04-20 or later).

1. Install the cargo-minicov tool:

cargo install cargo-minicov

2. Ensure that the following environment variables are set up:

export CARGO_INCREMENTAL=0
export RUSTFLAGS="-Zprofile -Zno-profiler-runtime -Copt-level=0 -Clink-dead-code -Coverflow-checks=off"

Note that the use of these flags may cause build-dependencies and proc macros to fail to compile. This can be worked around by explicitly specifying a target when invoking cargo:

# Fails to compile
cargo build

# Works
cargo build --target x86_64-unknown-linux-gnu

3. Add the minicov crate as a dependency to your program:

[dependencies]
minicov = "0.1"

4. (optional) The profiling instrumentation generated by LLVM relies on global constructors to work. This will generally work out of the box on most systems. However if your program runs on bare metal then you may need to do this yourself. minicov provides a helper function for this:

unsafe {
    minicov::run_static_constructors();
}

WARNING: Make sure you don't call static constructors again if your runtime has already done this for you. Doing so is undefined behavior and may result in crashes and/or data corruption.

5. Before your program exits, call minicov::capture_coverage which returns a Vec<u8> and dump its contents to a file:

fn main() {
    // ...

    let coverage = minicov::capture_coverage().unwrap();
    std::fs::write("output.minicov", coverage).unwrap();
}

If your program is running on a different system than your build system then you will need to transfer this file back to your build system.

6. After your program finishes running, use the cargo minicov command to generate GCOV .gcda files from the captured coverage:

cargo minicov output.minicov

You can pass multiple input files to cargo minicov, or even concatenate multiple input files into a single file:

cargo minicov a.minicov b.minicov

# Or

cat a.minicov b.minicov > combined.minicov
cargo minicov combined.minicov

7. Use your favorite GCOV-compatible coverage tool (e.g. grcov) to process the .gcda files.

grcov ./target/x86_64-unknown-linux-gnu/debug/ -s . -t html --llvm --branch --ignore-not-existing -o ./target/debug/coverage/

Change log

License

Licensed under either of:

• Apache License, Version 2.0, (LICENSE-APACHE or http://www.apache.org/licenses/LICENSE-2.0)
• MIT license (LICENSE-MIT or http://opensource.org/licenses/MIT)

at your option.

Contribution

Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.