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.

A Gcovr config file replaces Ceedling's own automatically generated exclusion patterns (see Results filtering below) entirely — it is the only way to override or remove one of those defaults, since the project-configuration :report_exclude option can only add further exclusions on top of them, never take one away. To preserve the same filtering of test and build files when switching to a Gcovr config file, you must provide equivalent explicit exclusion patterns matching your project layout yourself (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$

Results filtering

By default, this plugin configures gcovr to excludes three categories of .c files from coverage results. These defaults exist because a coverage percentage is typically only meaningful over the production code you're actually trying to exercise with test coverage. Test code, test support code, and every file Ceedling itself generates as part of a build will skew that number if left in coverage reporting.

The list that follows details the filtering this plugin injects into Gcovr coverage report generation. The examples are usable regular expressions that mirror the defaults in use. The plugin dynamically generates these regular expressions from your project configuration. When creating them youself, you will need to match your project configuration settings with static strings.

Test files — matched by :test_file_prefix within your configured :paths ↳ :test directories.

Given :test_file_prefix ⇒ test_ and a :paths ↳ :test entry of test/:
```
.*test/.*/test_.+\.c$
```
Test support files — any .c file within your configured :paths ↳ :support directories, regardless of name. Helpers, stubs, and fixtures living there are no more production code than the test files themselves.

Given a :paths ↳ :support entry of test/support/:
```
.*test/support/.+\.c$
```
Generated and vendored files — any .c file anywhere below your :build_root: generated mocks, test runners, Partials output, and the vendored Unity/CMock/CException framework sources Ceedling copies in to build against. This pattern always matches a literal .c extension regardless of your project's own :extension ↳ :source setting, since every file it catches is one Ceedling itself writes in plain C.

Given :build_root ⇒ build/:
```
.*build/.+\.c$
```

These patterns are generated automatically and combined with whatever you provide via :report_exclude below.

Not applied when using a Gcovr configuration file

These defaults are only generated when Ceedling builds gcovr's command line directly. As covered in Gcovr configuration file above, setting :config_file bypasses this entirely — none of the three patterns above are applied, and you must supply equivalent exclusions in the config file yourself.

Overriding the defaults

:report_exclude can only add exclusions on top of the three defaults above — gcovr --exclude is a deny-list with no way to "un-exclude" a pattern already passed to it, and this plugin always passes its own three patterns ahead of anything you configure there. Setting :report_include doesn't help either; it narrows which files are considered at all, but an exclude pattern still wins over it for any file matching both.

The only way to actually remove or replace one of these defaults — for example, to include test files in coverage results so you can confirm a conditional test build compiled the branches you expect — is a Gcovr configuration file. Setting :config_file stops Ceedling from generating any of the three patterns at all, handing you full control:

; gcovr.cfg — omits the test-file exclude pattern so test files remain in
; coverage results, while still keeping generated/vendored build output out.
exclude = .*build/.+\.c$

:gcov:
  :gcovr:
    :config_file: gcovr.cfg

Note that this isn't scoped per category. Once a default is dropped, any file it would have excluded is folded into the same combined report as your production code, not broken out separately.

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)

gcovr treats --fail-under-decision as a no-op without --decisions also present — setting this option implies :decisions (below) automatically, so it's never silently non-functional.

Values: 1–100

Requires: gcovr 7.0 or higher

`:decisions`

Report the decision coverage. For HTML, JSON, and the summary report. (gcovr --decisions)

Implied automatically whenever :fail_under_decision is set.

Requires: gcovr 5.1 or higher

`: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. Uses gcovr --txt-metric branch on gcovr 7.0+ (--branches is deprecated as of 7.0, though still functional); gcovr --branches below it.

`:sort_uncovered`

Sort entries by increasing number of uncovered lines. Applies to text and HTML reports. Uses gcovr --sort uncovered-number on gcovr 7.0+ (--sort-uncovered is deprecated as of 7.0, though still functional); gcovr --sort-uncovered below it.

`:sort_percentage`

Sort entries by increasing percentage of uncovered lines. Applies to text and HTML reports. Uses gcovr --sort uncovered-percent on gcovr 7.0+ (--sort-percentage is deprecated as of 7.0, though still functional); gcovr --sort-percentage below it.

`: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)

This narrows which files are considered at all, but does not override Results filtering's automatic exclusion defaults — a file excluded by one of those three default patterns stays excluded even if it also matches :report_include. See Overriding the defaults if you need to remove one of them.

Example: "^src"

`:report_exclude`

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

Ceedling automatically generates and prepends its own exclusion patterns for test files, test support files, and generated/vendored build files — see Results filtering above for exactly what these cover and why. Anything you provide here is combined with those defaults, not a replacement for them. This option can only add further exclusions, never remove or override one of the three defaults. See Overriding the defaults for how to do that instead.

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.