Skip to content

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:

  1. Using one or more of the options documented below in the :gcov section of your project configuration.
  2. 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).

[gcovr]
; 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.

; 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 project configuration

The following is an exhaustive commented version of all GCovr configuration options exposed through your project configuration file. 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.

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).

: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. (gcovr --config)
    # Defaults to gcovr.cfg in the report_root directory if that file exists.
    #
    # 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. Only
    # :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 the following
    # patterns in your config file (adjust paths to match your project’s
    # :test_file_prefix, test paths, and :build_root settings):
    #
    #   [gcovr]
    #   exclude = .*test.*/test_.+\.c$
    #   exclude = .*build/.+\.c$
    :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>

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.

:gcov:
  :gcovr:
    # Override default text report filename.
    :text_artifact_filename: <filename>