{"id":13580012,"url":"https://github.com/mozilla/grcov","last_synced_at":"2025-04-23T21:02:01.326Z","repository":{"id":37549665,"uuid":"83496508","full_name":"mozilla/grcov","owner":"mozilla","description":"Rust tool to collect and aggregate code coverage data for multiple source files","archived":false,"fork":false,"pushed_at":"2025-04-14T16:55:57.000Z","size":6042,"stargazers_count":1249,"open_issues_count":135,"forks_count":158,"subscribers_count":19,"default_branch":"master","last_synced_at":"2025-04-20T15:22:20.605Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mpl-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/mozilla.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE-MPL-2.0","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2017-03-01T01:17:55.000Z","updated_at":"2025-04-17T20:26:53.000Z","dependencies_parsed_at":"2023-02-13T00:46:24.276Z","dependency_job_id":"ecd4406c-3903-4c1c-a774-5b80691bb6c4","html_url":"https://github.com/mozilla/grcov","commit_stats":{"total_commits":1022,"total_committers":94,"mean_commits":"10.872340425531915","dds":0.4931506849315068,"last_synced_commit":"c8219563bc91615dd4a27884a5c63f09db8d03bb"},"previous_names":[],"tags_count":95,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mozilla%2Fgrcov","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mozilla%2Fgrcov/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mozilla%2Fgrcov/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/mozilla%2Fgrcov/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/mozilla","download_url":"https://codeload.github.com/mozilla/grcov/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":250514767,"owners_count":21443208,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-08-01T15:01:46.047Z","updated_at":"2025-04-23T21:02:01.269Z","avatar_url":"https://github.com/mozilla.png","language":"Rust","readme":"# grcov\n\n[![Build Status](https://github.com/mozilla/grcov/actions/workflows/CICD.yml/badge.svg?branch=master)](https://github.com/mozilla/grcov/actions/workflows/CICD.yml)\n[![codecov](https://codecov.io/gh/mozilla/grcov/branch/master/graph/badge.svg)](https://codecov.io/gh/mozilla/grcov)\n[![crates.io](https://img.shields.io/crates/v/grcov.svg)](https://crates.io/crates/grcov)\n\ngrcov collects and aggregates code coverage information for multiple source files.\ngrcov processes .profraw and .gcda files which can be generated from llvm/clang or gcc.\ngrcov also processes lcov files (for JS coverage) and JaCoCo files (for Java coverage).\nLinux, macOS and Windows are supported.\n\nThis is a project initiated by Mozilla to gather code coverage results on Firefox.\n\n\u003c!-- omit in toc --\u003e\n## Table of Contents\n\n- [man grcov](#man-grcov)\n- [How to get grcov](#how-to-get-grcov)\n- [Usage](#usage)\n  - [Example: How to generate source-based coverage for a Rust project](#example-how-to-generate-source-based-coverage-for-a-rust-project)\n  - [Example: How to generate .gcda files for C/C++](#example-how-to-generate-gcda-files-for-cc)\n  - [Example: How to generate .gcda files for a Rust project](#example-how-to-generate-gcda-files-for-a-rust-project)\n  - [Generate a coverage report from coverage artifacts](#generate-a-coverage-report-from-coverage-artifacts)\n    - [LCOV output](#lcov-output)\n    - [Coveralls output](#coveralls-output)\n    - [grcov with Travis](#grcov-with-travis)\n    - [grcov with Gitlab](#grcov-with-gitlab)\n  - [Alternative reports](#alternative-reports)\n  - [Hosting HTML reports and using coverage badges](#hosting-html-reports-and-using-coverage-badges)\n    - [Example](#example)\n  - [Enabling symlinks on Windows](#enabling-symlinks-on-windows)\n- [Auto-formatting](#auto-formatting)\n- [Build \u0026 Test](#build--test)\n- [Minimum requirements](#minimum-requirements)\n- [License](#license)\n\n## man grcov\n\n```text\nUsage: grcov [OPTIONS] \u003cPATHS\u003e...\n\nArguments:\n  \u003cPATHS\u003e...\n          Sets the input paths to use\n\nOptions:\n  -b, --binary-path \u003cPATH\u003e\n          Sets the path to the compiled binary to be used\n\n      --llvm-path \u003cPATH\u003e\n          Sets the path to the LLVM bin directory\n\n  -t, --output-types \u003cOUTPUT TYPE\u003e\n          Comma separated list of custom output types:\n          - *html* for a HTML coverage report;\n          - *coveralls* for the Coveralls specific format;\n          - *lcov* for the lcov INFO format;\n          - *covdir* for the covdir recursive JSON format;\n          - *coveralls+* for the Coveralls specific format with function information;\n          - *ade* for the ActiveData-ETL specific format;\n          - *files* to only return a list of files.\n          - *markdown* for human easy read.\n          - *cobertura* for output in cobertura format.\n          - *cobertura-pretty* to pretty-print in cobertura format.\n\n\n          [default: lcov]\n\n  -o, --output-path \u003cPATH\u003e\n          Specifies the output path. This is a file for a single output type and must be a folder\n          for multiple output types\n\n      --output-config-file \u003cPATH\u003e\n          Specifies the output config file\n\n  -s, --source-dir \u003cDIRECTORY\u003e\n          Specifies the root directory of the source files\n\n  -p, --prefix-dir \u003cPATH\u003e\n          Specifies a prefix to remove from the paths (e.g. if grcov is run on a different machine\n          than the one that generated the code coverage information)\n\n      --ignore-not-existing\n          Ignore source files that can't be found on the disk\n\n      --ignore \u003cPATH\u003e\n          Ignore files/directories specified as globs\n\n      --keep-only \u003cPATH\u003e\n          Keep only files/directories specified as globs\n\n      --path-mapping \u003cPATH\u003e\n\n\n      --branch\n          Enables parsing branch coverage information\n\n      --filter \u003cFILTER\u003e\n          Filters out covered/uncovered files. Use 'covered' to only return covered files,\n          'uncovered' to only return uncovered files\n\n          [possible values: covered, uncovered]\n\n      --llvm\n          Speeds-up parsing, when the code coverage information is exclusively coming from a llvm\n          build\n\n      --token \u003cTOKEN\u003e\n          Sets the repository token from Coveralls, required for the 'coveralls' and 'coveralls+'\n          formats\n\n      --commit-sha \u003cCOMMIT HASH\u003e\n          Sets the hash of the commit used to generate the code coverage data\n\n      --service-name \u003cSERVICE NAME\u003e\n          Sets the service name\n\n      --service-number \u003cSERVICE NUMBER\u003e\n          Sets the service number\n\n      --service-job-id \u003cSERVICE JOB ID\u003e\n          Sets the service job id\n\n          [aliases: service-job-number]\n\n      --service-pull-request \u003cSERVICE PULL REQUEST\u003e\n          Sets the service pull request number\n\n      --parallel\n          Sets the build type to be parallel for 'coveralls' and 'coveralls+' formats\n\n      --threads \u003cNUMBER\u003e\n\n\n      --precision \u003cNUMBER\u003e\n          Sets coverage decimal point precision on output reports\n\n          [default: 2]\n\n      --guess-directory-when-missing\n\n\n      --vcs-branch \u003cVCS BRANCH\u003e\n          Set the branch for coveralls report. Defaults to 'master'\n\n          [default: master]\n\n      --log \u003cLOG\u003e\n          Set the file where to log (or stderr or stdout). Defaults to 'stderr'\n\n          [default: stderr]\n\n      --log-level \u003cLEVEL\u003e\n          Set the log level\n\n          [default: ERROR]\n          [possible values: OFF, ERROR, WARN, INFO, DEBUG, TRACE]\n\n      --excl-line \u003cregex\u003e\n          Lines in covered files containing this marker will be excluded\n\n      --excl-start \u003cregex\u003e\n          Marks the beginning of an excluded section. The current line is part of this section\n\n      --excl-stop \u003cregex\u003e\n          Marks the end of an excluded section. The current line is part of this section\n\n      --excl-br-line \u003cregex\u003e\n          Lines in covered files containing this marker will be excluded from branch coverage\n\n      --excl-br-start \u003cregex\u003e\n          Marks the beginning of a section excluded from branch coverage. The current line is part\n          of this section\n\n      --excl-br-stop \u003cregex\u003e\n          Marks the end of a section excluded from branch coverage. The current line is part of this\n          section\n\n      --no-demangle\n          No symbol demangling\n\n  -h, --help\n          Print help (see a summary with '-h')\n\n  -V, --version\n          Print version\n```\n\n## How to get grcov\n\nGrcov can be downloaded from [releases](https://github.com/mozilla/grcov/releases) or, if you have Rust installed,\nyou can run `cargo install grcov`.\n\n## Usage\n\n### Example: How to generate source-based coverage for a Rust project\n\n1. Install the llvm-tools or llvm-tools-preview component:\n\n   ```sh\n   rustup component add llvm-tools-preview\n   ```\n\n2. Ensure that the following environment variable is set up:\n\n   ```sh\n   export RUSTFLAGS=\"-Cinstrument-coverage\"\n   ```\n\n3. Build your code:\n\n   `cargo build`\n\n4. 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):\n\n   ```sh\n   export LLVM_PROFILE_FILE=\"your_name-%p-%m.profraw\"\n   ```\n\n5. Run your tests:\n\n   `cargo test`\n\nIn the CWD, you will see a `.profraw` file has been generated. This contains the profiling information that grcov will parse, alongside with your binaries.\n\n### Example: How to generate .gcda files for C/C++\n\nPass `--coverage` to `clang` or `gcc` (or for older gcc versions pass `-ftest-coverage` and `-fprofile-arcs` options (see [gcc docs](https://gcc.gnu.org/onlinedocs/gcc/Gcov-Data-Files.html)).\n\n### Example: How to generate .gcda files for a Rust project\n\n**Nightly Rust is required** to use grcov for Rust gcov-based coverage. Alternatively, you can `export\nRUSTC_BOOTSTRAP=1`, which basically turns your stable rustc into a Nightly one.\n\n1. Ensure that the following environment variables are set up:\n\n   ```sh\n   export CARGO_INCREMENTAL=0\n   export RUSTFLAGS=\"-Zprofile -Ccodegen-units=1 -Copt-level=0 -Clink-dead-code -Coverflow-checks=off -Zpanic_abort_tests -Cpanic=abort\"\n   export RUSTDOCFLAGS=\"-Cpanic=abort\"\n   ```\n\n   These will ensure that things like dead code elimination do not skew the coverage.\n\n2. Build your code:\n\n   `cargo build`\n\n   If you look in `target/debug/deps` dir you will see `.gcno` files have appeared. These are the locations that could be covered.\n\n3. Run your tests:\n\n   `cargo test`\n\n   In the `target/debug/deps/` dir you will now also see `.gcda` files. These contain the hit counts on which of those locations have been reached. Both sets of files are used as inputs to `grcov`.\n\n### Generate a coverage report from coverage artifacts\n\nGenerate a html coverage report like this:\n\n```sh\ngrcov . -s . --binary-path ./target/debug/ -t html --branch --ignore-not-existing -o ./target/debug/coverage/\n```\n\nN.B.: The `--binary-path` argument is only necessary for source-based coverage.\n\nYou can see the report in `target/debug/coverage/index.html`.\n\n(or alternatively with `-t lcov` grcov will output a lcov compatible coverage report that you could then feed into lcov's `genhtml` command).\n\n#### LCOV output\n\nBy passing `-t lcov` you could generate an lcov.info file and pass it to genhtml:\n\n```sh\ngenhtml -o ./target/debug/coverage/ --show-details --highlight --ignore-errors source --legend ./target/debug/lcov.info\n```\n\nLCOV output should be used when uploading to Codecov, with the `--branch` argument for branch coverage support.\n\n#### Coveralls output\n\nCoverage can also be generated in coveralls format:\n\n```sh\ngrcov . --binary-path ./target/debug/ -t coveralls -s . --token YOUR_COVERALLS_TOKEN \u003e coveralls.json\n```\n\n#### grcov with Travis\n\nHere is an example of .travis.yml file for source-based coverage:\n\n```yaml\nlanguage: rust\n\nbefore_install:\n  - curl -L https://github.com/mozilla/grcov/releases/latest/download/grcov-x86_64-unknown-linux-gnu.tar.bz2 | tar jxf -\n\nmatrix:\n  include:\n    - os: linux\n      rust: stable\n\nscript:\n    - rustup component add llvm-tools-preview\n    - export RUSTFLAGS=\"-Cinstrument-coverage\"\n    - cargo build --verbose\n    - LLVM_PROFILE_FILE=\"your_name-%p-%m.profraw\" cargo test --verbose\n    - ./grcov . --binary-path ./target/debug/ -s . -t lcov --branch --ignore-not-existing --ignore \"/*\" -o lcov.info\n    - bash \u003c(curl -s https://codecov.io/bash) -f lcov.info\n```\n\nHere is an example of .travis.yml file:\n\n```yaml\nlanguage: rust\n\nbefore_install:\n  - curl -L https://github.com/mozilla/grcov/releases/latest/download/grcov-x86_64-unknown-linux-gnu.tar.bz2 | tar jxf -\n\nmatrix:\n  include:\n    - os: linux\n      rust: stable\n\nscript:\n    - export CARGO_INCREMENTAL=0\n    - export RUSTFLAGS=\"-Zprofile -Ccodegen-units=1 -Copt-level=0 -Clink-dead-code -Coverflow-checks=off -Zpanic_abort_tests -Cpanic=abort\"\n    - export RUSTDOCFLAGS=\"-Cpanic=abort\"\n    - cargo build --verbose $CARGO_OPTIONS\n    - cargo test --verbose $CARGO_OPTIONS\n    - |\n      zip -0 ccov.zip `find . \\( -name \"YOUR_PROJECT_NAME*.gc*\" \\) -print`;\n      ./grcov ccov.zip -s . -t lcov --llvm --branch --ignore-not-existing --ignore \"/*\" -o lcov.info;\n      bash \u003c(curl -s https://codecov.io/bash) -f lcov.info;\n```\n\n#### grcov with Gitlab\n\nHere 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.\n\n```yaml\nbuild:\n  variables:\n    # Set an environment variable which causes LLVM to write coverage data to the specified location. This is arbitrary, but the path passed to grcov (the first argument) must contain these files or the coverage data won't be noticed.\n    LLVM_PROFILE_FILE: \"target/coverage/%p-%m.profraw\"\n  script:\n    # Run all your Rust-based tests\n    - cargo test --workspace\n    # Optionally, run some other command that exercises your code to get more coverage:\n    - ./bin/integration-tests --foo bar\n    # Create the output directory\n    - mkdir target/coverage\n    # This is a multi-line command. You can also write it all as one line if desired, just remove\n    # the '|' and all the newlines.\n    - |\n        grcov\n    # This path must match the setting in LLVM_PROFILE_FILE. If you're not getting the coverage\n    # you expect, look for '.profraw' files in other directories.\n        target/coverage\n    # If your target dir is modified, this will need to match...\n        --binary-path target/debug\n    # Where the source directory is expected\n        -s .\n    # Where to write the output; this should be a directory that exists.\n        -o target/coverage\n    # Exclude coverage of crates and Rust stdlib code. If you get unexpected coverage results from\n    # this (empty, for example), try different combinations of '--ignore-not-existing',\n    # '--ignore \"$HOME/.cargo/**\"' and see what kind of filtering gets you the coverage you're\n    # looking for.\n        --keep-only 'src/*'\n    # Doing both isn't strictly necessary, if you won't use the HTML version you can modify this\n    # line.\n        --output-types html,cobertura\n\n    # Extract just the top-level coverage number from the XML report.\n    - xmllint --xpath \"concat('Coverage: ', 100 * string(//coverage/@line-rate), '%')\" target/coverage/cobertura.xml\n  coverage: '/Coverage: \\d+(?:\\.\\d+)?/'\n  artifacts:\n    paths:\n      - target/coverage/\n    reports:\n      coverage_report:\n        coverage_format: cobertura\n        path: target/coverage.xml\n```\n\nThis also ties into Gitlab's coverage percentage collection, so in merge requests you'll be able to see:\n\n- increases or decreases of coverage\n- whether particular lines of code modified by a merge request are covered or not.\n\nAdditionally, the HTML-formatted coverage report (if you leave it enabled) will be produced as an artifact.\n\n### Alternative reports\n\ngrcov provides the following output types:\n\n| Output Type `-t` | Description                                                               |\n| ---------------- | ------------------------------------------------------------------------- |\n| lcov (default)   | lcov's INFO format that is compatible with the linux coverage project.    |\n| ade              | ActiveData\\-ETL format. Only useful for Mozilla projects.                 |\n| coveralls        | Generates coverage in Coveralls format.                                   |\n| coveralls+       | Like coveralls but with function level information.                       |\n| files            | Output a file list of covered or uncovered source files.                  |\n| covdir           | Provides coverage in a recursive JSON format.                             |\n| html             | Output a HTML coverage report, including coverage badges for your README. |\n| cobertura        | Cobertura XML. Used for coverage analysis in some IDEs and Gitlab CI.     |\n| cobertura-pretty | Pretty-printed Cobertura XML.                                             |\n\n### Hosting HTML reports and using coverage badges\n\nThe HTML report can be hosted on static website providers like GitHub Pages, Netlify and others. It\nis common to provide a coverage badge in a project's readme to show the current percentage of\ncovered code.\n\nTo still allow adding the badge when using a static site host, grcov generates coverage badges and\na JSON file with coverage information that can be used with \u003chttps://shields.io\u003e to dynamically\ngenerate badges.\n\nThe coverage data for \u003chttps://shields.io\u003e can be found at `/coverage.json` and the generated\nbagdes are available as SVGs at `/badges/*svg`.\n\nThe design of generated badges is taken from `shields.io` but may not be updated immediately if there\nis any change. Using their endpoint method is recommended if other badges from their service are\nused already.\n\n### Enabling symlinks on Windows\n\n`grcov` uses symbolic links to avoid copying files, when processing directories\nof coverage data. On Windows, by default, creating symbolic links to files\nrequires Administrator privileges. (The reason is to avoid security attacks in\napplications that were designed before Windows added support for symbolic\nlinks.)\n\nWhen running on Windows `grcov` will attempt to create a symbolic link. If that\nfails then `grcov` will fall back to copying the file. Copying is less efficient\nbut at least allows users to run `grcov`. `grcov` will also print a warning\nwhen it falls back to copying a file, advising the user either to enable the\nprivilege for their account or to run as Administrator.\n\nYou can enable the \"Create Symbolic Links\" privilege for your account so that\nyou do not need to run as Administrator to use `grcov`.\n\n1. Click Start, then select \"Local Group Policy Editor\". Or just run\n   `gpedit.msc` to open it directly.\n1. In the navigation tree, select \"Computer Configuration\", \"Windows Settings\",\n   \"Security Settings\", \"Local Policies\", \"User Rights Assignment\".\n1. In the pane on the right, select \"Create symbolic links\" and double-click it.\n1. Click \"Add User or Group\", and add your account.\n1. Log out and then log back in.\n\n#### Example\n\nLet's consider we have a project at with username `sample` and project `awesome` that is hosted with\nGitHub Pages at `https://sample.github.io/awesome`.\n\nBy using the the `shields.io` endpoint we can create a Markdown badge like so:\n\n```md\n[![coverage](https://shields.io/endpoint?url=https://sample.github.io/awesome/coverage.json)](https://sample.github.io/awesome/index.html)\n```\n\nIf we want to avoid using `shields.io` as well, we can use the generated badges as follows (note\nthe different URL for the image):\n\n```md\n[![coverage](https://sample.github.io/awesome/badges/flat.svg)](https://sample.github.io/awesome/index.html)\n```\n\n## Auto-formatting\n\nThis 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](https://pre-commit.com/#install).\n\nEvery 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.\n\n## Build \u0026 Test\n\nBuild with:\n\n```sh\ncargo build\n```\n\nTo run unit tests:\n\n```sh\ncargo test --lib\n```\n\nTo run integration tests, it is suggested to use the Docker image defined in tests/Dockerfile. Simply build the image to run them:\n\n```sh\ndocker build -t marcocas/grcov -f tests/Dockerfile .\n```\n\nOtherwise, 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:\n\n```sh\ncargo test\n```\n\n## Minimum requirements\n\n- GCC 4.9 or higher is required (if parsing coverage artifacts generated by GCC).\n- Rust 1.52\n\n## License\n\nPublished under the MPL 2.0 license.\n","funding_links":[],"categories":["Rust","Other"],"sub_categories":[],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmozilla%2Fgrcov","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmozilla%2Fgrcov","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmozilla%2Fgrcov/lists"}