grcov

grcov

grcov collects and aggregates code coverage information for multiple source files. grcov processes .profraw and .gcda files which can be generated from llvm/clang or gcc. grcov also processes lcov files (for JS coverage), out files (for Go coverage), and JaCoCo files (for Java and Kotlin coverage). Linux, macOS and Windows are supported.

This is a project initiated by Mozilla to gather code coverage results on Firefox.

Table of Contents

• man grcov
• How to get grcov
• Usage
  • Example: How to generate source-based coverage for a Rust project
  • Example: How to generate .gcda files for C/C++
  • Generate a coverage report from coverage artifacts
    • LCOV output
    • Coveralls output
    • grcov with Travis
    • grcov with Gitlab
  • Alternative reports
  • Hosting HTML reports and using coverage badges
    • Example
  • Enabling symlinks on Windows
• Auto-formatting
• Build & Test
• Minimum requirements
• License

man grcov

…

How to get grcov

Grcov can be downloaded from releases or, if you have Rust installed, you can run cargo install grcov.

Usage

Example: How to generate source-based coverage for a Rust project

1. Install the llvm-tools or llvm-tools component:

   bash复制

   rustup component add llvm-tools

2. Ensure that the following environment variable is set up:

   bash复制

   export RUSTFLAGS="-Cinstrument-coverage"

3. Build your code:

   cargo build

4. Ensure each test runs gets its own profile information by defining the LLVM_PROFILE_FILE environment variable (%p will be replaced by the process ID, and %m by the binary signature):

   bash复制

   export LLVM_PROFILE_FILE="your_name-%p-%m.profraw"

5. Run your tests:

   cargo test

In the CWD, you will see a .profraw file has been generated. This contains the profiling information that grcov will parse, alongside with your binaries.

Note that gcov coverage using the -Zprofile flag is no longer supported in Rust (details here). Use source based coverage and the -Cinstrument-coverage flag instead.

Example: How to generate .gcda files for C/C++

Pass --coverage to clang or gcc (or for older gcc versions pass -ftest-coverage and -fprofile-arcs options (see gcc docs).

Generate a coverage report from coverage artifacts

Generate a html coverage report like this:

grcov . -s . --binary-path ./target/debug/ -t html --branch --ignore-not-existing -o ./target/debug/coverage/

N.B.: The --binary-path argument is only necessary for source-based coverage.

You can see the report in target/debug/coverage/index.html.

(or alternatively with -t lcov grcov will output a lcov compatible coverage report that you could then feed into lcov's genhtml command).

LCOV output

By passing -t lcov you could generate an lcov.info file and pass it to genhtml:

genhtml -o ./target/debug/coverage/ --show-details --highlight --ignore-errors source --legend ./target/debug/lcov.info

LCOV output should be used when uploading to Codecov, with the --branch argument for branch coverage support.

Coveralls output

Coverage can also be generated in coveralls format:

grcov . --binary-path ./target/debug/ -t coveralls -s . --token YOUR_COVERALLS_TOKEN > coveralls.json

grcov with Travis

Here is an example of .travis.yml file for source-based coverage:

language: rust

before_install:
  - curl -L https://github.com/mozilla/grcov/releases/latest/download/grcov-x86_64-unknown-linux-gnu.tar.bz2 | tar jxf -

matrix:
  include:
    - os: linux
      rust: stable

script:
    - rustup component add llvm-tools
    - export RUSTFLAGS="-Cinstrument-coverage"
    - cargo build --verbose
    - LLVM_PROFILE_FILE="your_name-%p-%m.profraw" cargo test --verbose
    - ./grcov . --binary-path ./target/debug/ -s . -t lcov --branch --ignore-not-existing --ignore "/*" -o lcov.info
    - bash <(curl -s https://codecov.io/bash) -f lcov.info

grcov with Gitlab

Here is an example .gitlab-ci.yml which will build your project, then collect coverage data in a format that Gitlab understands. It is assumed that you'll use an image which already has relevant tools installed, if that's not the case put the appropriate commands at the beginning of the script stanza.

…

This also ties into Gitlab's coverage percentage collection, so in merge requests you'll be able to see:

• increases or decreases of coverage
• whether particular lines of code modified by a merge request are covered or not.

Additionally, the HTML-formatted coverage report (if you leave it enabled) will be produced as an artifact.

Alternative reports

grcov provides the following output types:

Hosting HTML reports and using coverage badges

The HTML report can be hosted on static website providers like GitHub Pages, Netlify and others. It is common to provide a coverage badge in a project's readme to show the current percentage of covered code.

To still allow adding the badge when using a static site host, grcov generates coverage badges and a JSON file with coverage information that can be used with https://shields.io to dynamically generate badges.

The coverage data for https://shields.io can be found at /coverage.json and the generated bagdes are available as SVGs at /badges/*svg.

The design of generated badges is taken from shields.io but may not be updated immediately if there is any change. Using their endpoint method is recommended if other badges from their service are used already.

Enabling symlinks on Windows

grcov uses symbolic links to avoid copying files, when processing directories of coverage data. On Windows, by default, creating symbolic links to files requires Administrator privileges. (The reason is to avoid security attacks in applications that were designed before Windows added support for symbolic links.)

When running on Windows grcov will attempt to create a symbolic link. If that fails then grcov will fall back to copying the file. Copying is less efficient but at least allows users to run grcov. grcov will also print a warning when it falls back to copying a file, advising the user either to enable the privilege for their account or to run as Administrator.

You can enable the "Create Symbolic Links" privilege for your account so that you do not need to run as Administrator to use grcov.

1. Click Start, then select "Local Group Policy Editor". Or just run gpedit.msc to open it directly.
2. In the navigation tree, select "Computer Configuration", "Windows Settings", "Security Settings", "Local Policies", "User Rights Assignment".
3. In the pane on the right, select "Create symbolic links" and double-click it.
4. Click "Add User or Group", and add your account.
5. Log out and then log back in.

Example

Let's consider we have a project at with username sample and project awesome that is hosted with GitHub Pages at https://sample.github.io/awesome.

By using the the shields.io endpoint we can create a Markdown badge like so:

If we want to avoid using shields.io as well, we can use the generated badges as follows (note the different URL for the image):

Auto-formatting

This project is using pre-commit. Please run pre-commit install to install the git pre-commit hooks on your clone. Instructions on how to install pre-commit can be found here.

Every time you will try to commit, pre-commit will run checks on your files to make sure they follow our style standards and they aren't affected by some simple issues. If the checks fail, pre-commit won't let you commit.

Build & Test

Build with:

cargo build

To run unit tests:

cargo test --lib

To run integration tests, it is suggested to use the Docker image defined in tests/Dockerfile. Simply build the image to run them:

docker build -t marcocas/grcov -f tests/Dockerfile .

Otherwise, if you don't want to use Docker, the only prerequisite is to install GCC 7, setting the GCC_CXX environment variable to g++-7 and the GCOV environment variable to gcov-7. Then run the tests with:

cargo test

Minimum requirements

• GCC 4.9 or higher is required (if parsing coverage artifacts generated by GCC).
• Rust 1.52

License

Published under the MPL 2.0 license.