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), --config (:config_file), and any :custom_args: to gcovr at the command line from your plugin configuration. This prevents overriding config file settings with other CLI arguments derived from plugin configuration. You must provide any settings that would have been provided by the Gcov plugin, either in the config file itself or via :custom_args:.

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, gcovr excludes three categories of .c files from coverage results, on top of whatever gcov itself already limits reporting to (the sources your test build actually compiled). These defaults exist because a coverage percentage is only meaningful over the production code you're actually trying to cover — test code, test support code, and every file Ceedling itself generates as part of a build all skew that number if left in.

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)$
```
A project's :extension ↳ :source can list more than one source extension; every configured extension is joined into this same alternation. Given :extension ↳ :source ⇒ ['.c', '.C']:
```
.*(?:^|/)test/(?:.*/)?test_[^/]+(?:\.c|\.C)$
```
Test support files — any file matching one of your configured source extensions 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)$
```
Again, every configured :extension ↳ :source value is included in the alternation. Given :extension ↳ :source ⇒ ['.c', '.C']:
```
.*(?:^|/)test/support/.+(?:\.c|\.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. Unlike the two patterns above, this one 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 — you don't need to (and normally shouldn't) duplicate them yourself.

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 Ceedling always passes its own three patterns ahead of anything you configure there. Neither :report_include nor :custom_args helps either: :report_include narrows which files are considered at all, but an exclude pattern still wins over it for any file matching both; :custom_args lets you pass additional raw gcovr flags, but a raw --filter/--exclude of your own is just as additive as :report_exclude — there's no gcovr flag that removes or replaces an exclusion already given, only ones that add more.

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. Ceedling does not derive a default :report_include from it — gcovr itself only searches beneath --root when no --filter is given.

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 (nearly) 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, and :custom_args: is still applied too — the one way to pass Gcovr flags of your own alongside a config file (see :custom_args below).

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: unset — Ceedling does not look for or autodetect a config file on disk; gcovr itself is only ever told to load one when :config_file is explicitly set.

`: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 (e.g. to include test files in results). 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)

`:custom_args`

Optional list of one or more raw command line arguments to pass to gcovr. Useful as an escape hatch for any gcovr flag Ceedling has no named option for (e.g. limiting gcovr's search root).

Unlike every other option above, these arguments are still applied even when :config_file is set — the one way to pass gcovr flags of your own alongside a config file.

This does not, on its own, let you override Results filtering's automatic exclusion defaults when :config_file is unset — a raw --filter/--exclude passed here is just as additive as :report_exclude; see Overriding the defaults for the one option that actually does.

:gcov:
  :gcovr:
    :custom_args:
      - <argument>
      - ...

Default: []

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.

JaCoCo XML reports

A JaCoCo XML report is a coverage format that Java-oriented tools and IDEs such as CLion import. Enable it with JaCoCo in :gcov ↳ :reports.

Requires: gcovr 7.0 or higher. An older gcovr stops the build.

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

`:jacoco_pretty`

Pretty-print the JaCoCo XML report. (gcovr --jacoco-pretty)

Default: false

`:jacoco_artifact_filename`

Override the default JaCoCo XML report output filename.

Default: GcovCoverageJaCoCo.xml

LCOV reports

An LCOV info file is the coverage format of the lcov toolset that many coverage viewers and services read. Enable it with lcov in :gcov ↳ :reports. ReportGenerator also writes lcov, each utility into its own artifacts folder.

Requires: gcovr 7.0 or higher. An older gcovr stops the build when it is the only enabled utility. With ReportGenerator also enabled, an older gcovr logs a warning and leaves lcov to ReportGenerator.

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

`:lcov_comment`

Set a comment in the LCOV report. (gcovr --lcov-comment)

`:lcov_test_name`

Set the test name recorded in the LCOV report. (gcovr --lcov-test-name)

`:lcov_artifact_filename`

Override the default LCOV report output filename.

Default: GcovCoverage.lcov

Text reports

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

`:text_artifact_filename`

Override the default text report output filename.

Default: coverage.txt