GCovr Configuration
All reports generated by gcovr are found in <build root>/artifacts/gcov/gcovr/.
HTML reports
Generation of HTML reports may be modified with the following configuration items.
:gcov:
:gcovr:
# HTML report filename.
:html_artifact_filename: <filename>
# Use 'title' as title for the HTML report.
# Default is 'Head'. (gcovr --html-title)
:html_title: <title>
# If the coverage is below MEDIUM, the value is marked as low coverage in the HTML report.
# MEDIUM has to be lower than or equal to value of html_high_threshold.
# If MEDIUM is equal to value of html_high_threshold the report has only high and low coverage.
# Default is 75.0. (gcovr --html-medium-threshold)
:html_medium_threshold: 75
# If the coverage is below HIGH, the value is marked as medium coverage in the HTML report.
# HIGH has to be greater than or equal to value of html_medium_threshold.
# If HIGH is equal to value of html_medium_threshold the report has only high and low coverage.
# Default is 90.0. (gcovr -html-high-threshold)
:html_high_threshold: 90
# Set to 'true' to use absolute paths to link the 'detailed' reports.
# Defaults to relative links. (gcovr --html-absolute-paths)
:html_absolute_paths: <true|false>
# Override the declared HTML report encoding. Defaults to UTF-8. (gcovr --html-encoding)
:html_encoding: <html_encoding>
Cobertura XML reports
Generation of Cobertura XML reports may be modified with the following configuration items.
:gcov:
:gcovr:
# Set to 'true' to pretty-print the Cobertura XML report, otherwise set to 'false'.
# Defaults to disabled. (gcovr --xml-pretty)
:cobertura_pretty: <true|false>
# Override default Cobertura XML report filename.
:cobertura_artifact_filename: <filename>
SonarQube XML reports
Generation of SonarQube XML reports may be modified with the following configuration items.
:gcov:
:gcovr:
# Override default SonarQube XML report filename.
:sonarqube_artifact_filename: <filename>
JSON reports
Generation of JSON reports may be modified with the following configuration items.
:gcov:
:gcovr:
# Set to 'true' to pretty-print the JSON report, otherwise set 'false'.
# Defaults to disabled. (gcovr --json-pretty)
:json_pretty: <true|false>
# Override default JSON report filename.
:json_artifact_filename: <filename>
Text reports
Generation of text reports may be modified with the following configuration items. Text reports may be printed to the console or output to a file.
Common GCovr options
A number of options exist to control which files are considered part of a coverage report. This Ceedling gcov plugin itself handles the most important aspect — only source files under test are compiled with coverage. Tests, mocks, and test runners, are not compiled with coverage.
gcovr accepts only one report root path
gcovr will only accept a single path for :report_root. In typical usage,
this is of no concern as it is handled automatically. In unusual project
layouts, you may need to specify a folder that encompasses all build folders
containing coverage result files and optionally, selectively exclude patterns
of paths or files. For instance, if your Ceedling project file is not at the
root of your project, you may need set :report_root as well as
:report_exclude and :exclude_directories.
:gcov:
:gcovr:
# The root directory of your source files. Defaults to ".", the current directory.
# File names are reported relative to this root. The report_root is the default report_include.
# Default if unspecified: "."
:report_root: <path>
# Load the specified configuration file.
# Defaults to gcovr.cfg in the report_root directory. (gcovr --config)
:config_file: <config_file>
# Exit with a status of 2 if the total line coverage is less than MIN percentage.
# Can be ORed with exit status of other fail options. (gcovr --fail-under-line)
:fail_under_line: <1-100>
# Exit with a status of 4 if the total branch coverage is less than MIN percentage.
# Can be ORed with exit status of other fail options. (gcovr --fail-under-branch)
:fail_under_branch: <1-100>
# Exit with a status of 8 if the total decision coverage is less than MIN percentage.
# Can be ORed with exit status of other fail options. (gcovr --fail-under-decision)
:fail_under_decision: <1-100>
# Exit with a status of 16 if the total function coverage is less than MIN percentage.
# Can be ORed with exit status of other fail options. (gcovr --fail-under-function)
:fail_under_function: <1-100>
# If the fail options above are set, specify whether those conditions should break a build.
# The default option is false and simply logs a warning without breaking the build.
:exception_on_fail: <true|false>
# Select the source file encoding.
# Defaults to the system default encoding (UTF-8). (gcovr --source-encoding)
:source_encoding: <encoding>
# Report the branch coverage instead of the line coverage. For text report only. (gcovr --branches).
:branches: <true|false>
# Sort entries by increasing number of uncovered lines.
# For text and HTML report. (gcovr --sort-uncovered)
:sort_uncovered: <true|false>
# Sort entries by increasing percentage of uncovered lines.
# For text and HTML report. (gcovr --sort-percentage)
:sort_percentage: <true|false>
# Print a small report to stdout with line & branch percentage coverage.
# This is in addition to other reports. (gcovr --print-summary).
:print_summary: <true|false>
# Keep only source files that match this filter. (gcovr --filter).
# Filters are regular expressions (ex: "^src")
:report_include: <filter>
# Exclude source files that match this filter. (gcovr --exclude).
# Filters are regular expressions (ex: "^vendor.*|^build.*|^test.*|^lib.*")
:report_exclude: <filter>
# Keep only gcov data files that match this filter. (gcovr --gcov-filter).
# Filters are regular expressions
:gcov_filter: <filter>
# Exclude gcov data files that match this filter. (gcovr --gcov-exclude).
# Filters are regular expressions
:gcov_exclude: <filter>
# Exclude directories that match this filter while searching
# raw coverage files. (gcovr --exclude-directories).
# Filters are regular expressions
:exclude_directories: <filters>
# Use a particular gcov executable. (gcovr --gcov-executable).
# (This may be appropriate and necessary in special circumstances.
# Please review Ceedling's options for modifying tools first.)
:gcov_executable: <cmd>
# Exclude branch coverage from lines without useful
# source code. (gcovr --exclude-unreachable-branches).
:exclude_unreachable_branches: <true|false>
# For branch coverage, exclude branches that the compiler
# generates for exception handling. (gcovr --exclude-throw-branches).
:exclude_throw_branches: <true|false>
# For Gcovr 6.0+, multiple instances of the same function in coverage results can
# cause a fatal error. Since Ceedling can test multiple build variations of the
# same source function, this is bad.
# Default value for Gcov plugin is 'merge-use-line-max'. See Gcovr docs for more.
# https://gcovr.com/en/stable/guide/merging.html
:merge_mode_function: <...>
# Use existing gcov files for analysis. Default: False. (gcovr --use-gcov-files)
:use_gcov_files: <true|false>
# Skip lines with parse errors in GCOV files instead of
# exiting with an error. (gcovr --gcov-ignore-parse-errors).
:gcov_ignore_parse_errors: <true|false>
# Override normal working directory detection. (gcovr --object-directory)
:object_directory: <path>
# Keep gcov files after processing. (gcovr --keep).
:keep: <true|false>
# Delete gcda files after processing. (gcovr --delete).
:delete: <true|false>
# Set the number of threads to use in parallel. (gcovr -j).
:threads: <count>