{"id":2517,"library":"gcovr","title":"Gcovr","description":"Gcovr is a Python utility that processes code coverage data generated by the GNU gcov tool for C/C++ projects. It simplifies the creation of summarized code coverage reports in various formats, including text, HTML, XML (Cobertura, SonarQube, JaCoCo), JSON, CSV, and Markdown. Gcovr is currently at version 8.6 and maintains a regular release cadence with several updates throughout the year.","status":"active","version":"8.6","language":"en","source_language":"en","source_url":"https://github.com/gcovr/gcovr","tags":["code coverage","c","c++","gcov","testing","development tools","report generation"],"install":[{"cmd":"pip install gcovr","lang":"bash","label":"Install stable release"}],"dependencies":[{"reason":"Required to compile C/C++ code with coverage instrumentation.","package":"gcc/g++","optional":false},{"reason":"The underlying utility that generates raw coverage data; gcovr processes its output.","package":"gcov","optional":false}],"imports":[{"note":"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.","symbol":"gcovr","correct":"gcovr"}],"quickstart":{"code":"# 1. Create a sample C++ file (example.cpp)\n#include <iostream>\n\nint foo(int param) {\n    if (param) {\n        return 1;\n    } else {\n        return 0;\n    }\n}\n\nint main() {\n    foo(0);\n    std::cout << \"Hello from main!\" << std::endl;\n    return 0;\n}\n\n# 2. Compile the code with coverage flags\ng++ -fprofile-arcs -ftest-coverage -O0 example.cpp -o program\n\n# 3. Run the compiled program to generate .gcda data files\n./program\n\n# 4. Generate a coverage report using gcovr (e.g., HTML report)\ngcovr -r . --html --html-details -o coverage.html\n\n# To view the report:\n# open coverage.html","lang":"bash","description":"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)."},"warnings":[{"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.","message":"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.","severity":"breaking","affected_versions":"<7.0 (for Python 3.7), <5.1 (for Python 3.6), <5.0 (for Python 2/3.5)"},{"fix":"Update any scripts or CI/CD pipelines that rely on gcovr's specific error exit codes to reflect the new values.","message":"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.","severity":"breaking","affected_versions":">=7.0"},{"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+).","message":"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.","severity":"gotcha","affected_versions":"All"},{"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`).","message":"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.","severity":"gotcha","affected_versions":"All"},{"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 ..`.","message":"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.","severity":"gotcha","affected_versions":"All"},{"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.","message":"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.","severity":"breaking","affected_versions":">=8.x"}],"env_vars":null,"last_verified":"2026-04-10T00:00:00.000Z","next_check":"2026-07-09T00:00:00.000Z"}