GCovr Configuration

Note

All reports generated by gcovr are found in <build root>/artifacts/gcov/gcovr/.

The following sections first discuss GCovr options in common across reports and then break out report-specific options.

GCovr options

Project config vs. GCovr config file

GCovr can be configured in two ways:

Using one or more of the options documented below in the :gcov section of your project configuration.
Through a Gcovr configuration file (.ini format) provided to Gcovr via the speciial :config_file value in the :gcov section of your project configuration.

Gcovr configuration file

Using a gcovr configuration file

When :config_file is set, Ceedling passes only --root (:report_root) and --config (:config_file) to gcovr at the command line from your plugin configuration. This prevents overriding config file settings with CLI arguments. You must provide any settings that would have been provided by the Gcov plugin.

To preserve filtering of test and build files from coverage results when using a Gcovr config file, you must provide explicit exclusion patterns matching your project layout (example below).

; You will need to revise these example exclude patterns to match your
; project directories and file naming as they cannot be automatically 
; provided to Gcovr when a Gcovr configuration file is in use.
;
; Note: Format is flat `key = value` lines with no `[section]` header.

; Test path(s) exclusions for 'test_' files with .c extensions. 
exclude = .*test.*/test_.+\.c$

; Build path exlcude for all generated C files (runners, mocks, partials).
exclude = .*build/.+\.c$

Plugin configuration

The following options are exposed through your project configuration file, all beneath :gcov ↳ :gcovr. Only specify those you need or those whose defaults you need to override. You do not need to include all these options in your Gcov plugin configuration.

`:report_root`

The root directory of your source files. File names are reported relative to this root. :report_root is also the default :report_include.

gcovr accepts only one reporting root path

gcovr accepts only a single path for :report_root. In unusual project layouts, you may need to specify as root a parent folder that includes all source files and selectively exclude paths or files from coverage reporting (see :report_exclude and :exclude_directories).

Default: "." (the current directory)

`:config_file`

Load the specified gcovr configuration file. (gcovr --config)

When :config_file is set, Ceedling passes only --root and --config to gcovr and defers all other configuration to the file. This prevents Ceedling from overriding config file values with its CLI arguments. :report_root is still applied because Ceedling may invoke gcovr from a different working directory than your project root.

To preserve the plugin's base filtering behavior, include exclusion patterns matching your project layout in the config file itself — see Gcovr configuration file above.

Default: gcovr.cfg in the :report_root directory, if that file exists.

`:fail_under_line`

Exit with a status of 2 if the total line coverage is less than this minimum percentage. Can be ORed with the exit status of other :fail_under_* options. (gcovr --fail-under-line)

Values: 1–100

`:fail_under_branch`

Exit with a status of 4 if the total branch coverage is less than this minimum percentage. Can be ORed with the exit status of other :fail_under_* options. (gcovr --fail-under-branch)

Values: 1–100

`:fail_under_decision`

Exit with a status of 8 if the total decision coverage is less than this minimum percentage. Can be ORed with the exit status of other :fail_under_* options. (gcovr --fail-under-decision)

Values: 1–100

`:fail_under_function`

Exit with a status of 16 if the total function coverage is less than this minimum percentage. Can be ORed with the exit status of other :fail_under_* options. (gcovr --fail-under-function)

Values: 1–100

`:exception_on_fail`

If any :fail_under_* option above is set and its condition is met, specifies whether that condition should break the build. When disabled, Ceedling simply logs a warning without breaking the build.

Default: false

`:source_encoding`

Select the source file character encoding. (gcovr --source-encoding)

Default: the system default encoding (typically UTF-8)

`:branches`

Report the branch coverage instead of the line coverage. Applies to the text report only. (gcovr --branches)

`:sort_uncovered`

Sort entries by increasing number of uncovered lines. Applies to text and HTML reports. (gcovr --sort-uncovered)

`:sort_percentage`

Sort entries by increasing percentage of uncovered lines. Applies to text and HTML reports. (gcovr --sort-percentage)

`:print_summary`

Print a small report to stdout with line and branch percentage coverage. This is in addition to any other configured reports. (gcovr --print-summary)

`:report_include`

Keep only source files that match this filter. Filters are regular expressions. (gcovr --filter)

Example: "^src"

`:report_exclude`

Exclude source files that match this filter. Filters are regular expressions. (gcovr --exclude)

Example: "^vendor.*|^build.*|^test.*|^lib.*"

`:gcov_filter`

Keep only .gcov data files that match this filter. Filters are regular expressions. (gcovr --gcov-filter)

`:gcov_exclude`

Exclude .gcov data files that match this filter. Filters are regular expressions. (gcovr --gcov-exclude)

`:exclude_directories`

Exclude directories that match this filter while searching for raw coverage files. Filters are regular expressions. (gcovr --exclude-directories)

`:gcov_executable`

Use a particular gcov executable. This may be appropriate and necessary in special circumstances — review Ceedling's options for modifying tools first. (gcovr --gcov-executable)

`:exclude_unreachable_branches`

Exclude branch coverage from lines without useful source code. (gcovr --exclude-unreachable-branches)

`:exclude_throw_branches`

For branch coverage, exclude branches that the compiler generates for exception handling. (gcovr --exclude-throw-branches)

`:merge_mode_function`

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 a real risk. This option controls how gcovr merges those repeated entries. See the gcovr merging docs for all valid values. Ignored on gcovr versions below 6.0.

Default: merge-use-line-max (gcovr's own default, strict, raises an exception for many Ceedling projects)

`:use_gcov_files`

Use existing .gcov files for analysis instead of running gcov again. (gcovr --use-gcov-files)

Default: false

`:gcov_ignore_parse_errors`

Skip lines with parse errors in .gcov files instead of exiting with an error. (gcovr --gcov-ignore-parse-errors)

`:object_directory`

Override normal working directory detection for .gcda/.gcno files. (gcovr --object-directory)

`:keep`

Keep intermediate .gcov files after processing. (gcovr --keep)

`:delete`

Delete .gcda files after processing. (gcovr --delete)

`:threads`

Set the number of threads gcovr uses in parallel. (gcovr -j)

HTML reports

Generation of HTML reports may be modified with the following configuration items.

`:html_artifact_filename`

Override the default HTML report output filename.

`:html_title`

Use title as the title for the HTML report. (gcovr --html-title)

Default: Head

`:html_medium_threshold`

If the coverage is below this value, it is marked as low coverage in the HTML report. Must be lower than or equal to :html_high_threshold. If equal to :html_high_threshold, the report has only high and low coverage. (gcovr --html-medium-threshold)

Default: 75.0

`:html_high_threshold`

If the coverage is below this value, it is marked as medium coverage in the HTML report. Must be greater than or equal to :html_medium_threshold. If equal to :html_medium_threshold, the report has only high and low coverage. (gcovr --html-high-threshold)

Default: 90.0

`:html_absolute_paths`

Use absolute paths to link the "detailed" reports. Defaults to relative links. (gcovr --html-absolute-paths)

`:html_encoding`

Override the declared HTML report encoding. (gcovr --html-encoding)

Default: UTF-8

Cobertura XML reports

Generation of Cobertura XML reports may be modified with the following configuration items.

`:cobertura_pretty`

Pretty-print the Cobertura XML report. (gcovr --xml-pretty)

Default: false

`:cobertura_artifact_filename`

Override the default Cobertura XML report output filename.

SonarQube XML reports

Generation of SonarQube XML reports may be modified with the following configuration items.

`:sonarqube_artifact_filename`

Override the default SonarQube XML report output filename.

JSON reports

Generation of JSON reports may be modified with the following configuration items.

`:json_pretty`

Pretty-print the JSON report. (gcovr --json-pretty)

Default: false

`:json_artifact_filename`

Override the default JSON report output 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.

`:text_artifact_filename`

Override the default text report output filename.