Gcovr

Warnings

• breaking Gcovr versions have dropped support for older Python versions. Version 7.0 dropped support for Python 3.7, and version 5.1 dropped Python 3.6 support. Version 5.0 removed support for Python 2 and Python 3.5.
  Fix: Ensure your environment uses Python 3.10 or newer for gcovr 8.x. Check gcovr's documentation for specific Python version requirements for older gcovr releases.
• breaking Exit codes for errors in the reader or writer modules have changed. In gcovr 7.0, a reader error's exit code changed from 8 to 64, and a writer error's from 7 to 128.
  Fix: Update any scripts or CI/CD pipelines that rely on gcovr's specific error exit codes to reflect the new values.
• gotcha Forgetting to recompile your C/C++ code with coverage flags (`-fprofile-arcs -ftest-coverage` or `--coverage`) after making changes, or not cleaning old object files, can lead to outdated or incorrect coverage data. Also, using `-O` optimization flags can sometimes obscure coverage information.
  Fix: Always perform a `make clean` or equivalent to clear old object files before recompiling with coverage flags. Compile with `-O0` (no optimization) for the most accurate coverage reports. For robust path handling, consider `-fprofile-abs-path` (GCC 8+).
• gotcha Gcovr relies on the `gcov` executable. If you have multiple GCC/Clang versions or custom installations, `gcovr` might pick the wrong `gcov` by default, leading to parsing errors or incorrect reports.
  Fix: Explicitly specify the correct `gcov` executable using the `--gcov-executable` option (e.g., `--gcov-executable 'llvm-cov gcov'` for Clang or `gcovr --gcov-executable gcov-8`).
• gotcha On Windows, issues with path separators (backslashes vs. forward slashes) and symlinks can cause `gcovr` to fail to find source files or generate detailed reports, especially when source files are in different directories from the build output.
  Fix: When using `--root` and filters, ensure paths are consistent. Consider using forward slashes even on Windows for filters. Ensure build systems handle paths correctly or run `gcovr` from the build directory with `--root ..`.
• breaking The internal data model for coverage information per line was improved in version 8.x. This removed the `function return count` from internal data model, HTML, and JSON output, and `function_name` for a line in JSON report is now always set.
  Fix: If you parse gcovr's JSON or XML reports programmatically, review your parsing logic to adapt to these data model changes and the new structure for function coverage.

Install

• pip install gcovr Install stable release

Imports

• gcovr

  gcovr

  Gcovr is primarily a command-line tool. Direct programmatic imports for general use are not common. Its Python entry point is `gcovr.__main__.py` for CLI execution.

Quickstart

This quickstart demonstrates the typical workflow for using gcovr: compiling your C/C++ code with GCC's coverage flags, executing your program to generate coverage data, and then running the `gcovr` command-line tool to produce a human-readable report (e.g., HTML).

# 1. Create a sample C++ file (example.cpp)
#include <iostream>

int foo(int param) {
    if (param) {
        return 1;
    } else {
        return 0;
    }
}

int main() {
    foo(0);
    std::cout << "Hello from main!" << std::endl;
    return 0;
}

# 2. Compile the code with coverage flags
g++ -fprofile-arcs -ftest-coverage -O0 example.cpp -o program

# 3. Run the compiled program to generate .gcda data files
./program

# 4. Generate a coverage report using gcovr (e.g., HTML report)
gcovr -r . --html --html-details -o coverage.html

# To view the report:
# open coverage.html