Skip to content

Set up & Configuration

Toolchain dependencies

GNU Compiler Collection

This plugin relies on the GNU compiler collection. Coverage instrumentation is enabled through gcc compiler flags. Coverage-insrumented executables (i.e. test suites) output coverage result files to disk when run. gcov, gcovr, and reportgenerator (the tools managed by this plugin) all produce their coverage tallies from these files. gcov is part of the GNU compiler collection. The other tools — detailed below — require separate installation.

Ceedling’s default toolchain is the same as needed by this plugin. If you are already running Ceedling test suites with the GNU compiler toolchain, you are good to go. If you are using another toolchain for test suite and/or release builds you will need to install the GNU compiler collection to use this plugin. Depending on your needs you may also need to install the reporting utilities, gcovr and/or reportgenerator.

gcovr and reportgenerator’s dependence on gcov

Both the gcovr and reportgenerator tools depend on the gcov tool. This dependency plays out in two different ways. In both cases, the report generation utilities ingest gcov’s output to produce their artifacts. As such, gcov must be available in your environment if using report generation.

  1. gcovr calls gcov directly.

    Because it calls gcov directly, you are limited as to the advanced Ceedling features you can employ to modify gcov’s execution. However, with a configuration option (see below) you can instruct gcovr to call something other than gcov (e.g. a script that intercepts and modifies how gcovr calls out to gcov).

    gcovr instructs gcov to generate .gcov files that it processes and discards. A gcovr option documented below will retain the .gcov files.

  2. reportgenerator expects the existence of .gcov files to do its work.

    This Ceedling plugin calls gcov appropriately to generate the .gcov files reportgenerator needs before then calling the report utility.

    You can use Ceedling’s features to modify how gcov is run before reportgenerator.

Enable this plugin

To use this plugin it must be enabled in your Ceedling project file:

:plugins:
  :enabled:
    - gcov

This simple configuration will create new gcov: command line tasks to run tests with source coverage and output simple coverage summaries to the console as above.

Disabling automatic coverage summaries

To disable the coverage summaries generated immediately following gcov: tasks, simply add the following to a top-level :gcov: section in your project configuration file.

:plugins:
  :enabled:
    - gcov

:gcov:
  :summaries: FALSE

Report generation

To generate reports:

  1. GCovr and / or ReportGenerator must installed or otherwise ready to run in Ceedling’s environment.
  2. Reporting options must be configured in your project file beneath a :gcov: entry.

The next sections explain each of these steps.

Modified Condition / Decision Coverage

As of version 14, the GNU Compiler Collection supports MC/DC. If your environment contains a minimum of GCC 14 you can enable MC/DC in coverage summaries.

If your environment contains a minimum of GCC 14 and GCovr 8, you can enable MC/DC in your generated coverage reports.

NOTE: ReportGenerator does not support MC/DC reporting.

:plugins:
  :enabled:
    - gcov

:gcov:
  :mcdc: TRUE
Default: FALSE

Coverage for untested sources

This setting controls how the GCov plugin handles project source files that are not exercised by any test. It takes one of three values:

  • :ignore — Untested source files are not processed at all. Nothing is logged, nothing is compiled, and these files are simply absent from the coverage report.
  • :list — Untested source files are not compiled with coverage, but their filepaths are logged as a warning so you know which files will not appear in the coverage report.
  • :compile — All untested source files are compiled with coverage so they appear in the final report with 0% coverage (since no test exercises them). This causes all source files to appear in any generated reporting. If a source file fails to compile, Ceedling logs guidance at the console, and the build fails.

:plugins:
  :enabled:
    - gcov

:gcov:
  :untested_sources: :list
Default: :list

Warning

Compiling all untested sources for 0% coverage reporting (:compile) will likely require additional work.

Successful compilation of untested source files may require certain symbols to be defined, certain flags to be set, or entire stand-in shims for platform headers and code.

Ceedling’s :defines and :flags matchers can provide these. For GCov tasks, symbols and flags are extracted from the :test context beneath the :defines and :flags configuration sections by default. If you need something special for coverage builds, use the :gcov context for these matchers instead.

Notes:

  • Versions of GCovr before 7.0 do not include the necessary options to produce 0% coverage results for source files only compiled (but never executed).

When :untested_sources is :compile, an additional gcov:untested_sources build task becomes available:

 > ceedling gcov:untested_sources

This task exists to let you work through the compilation problems described in the warning above — missing symbols, flags, or platform header/code stand-ins — by re-running just the untested-source compilation step directly. No test suite build is needed while iterating on source compilation fixes.

Reporting utilities installation

Variants of the madsciencelab Docker images come with these tools preinstalled

See the Docker image options for running Ceedling.

gcovr is available on any platform supported by Python.

gcovr can be installed via pip like this:

 > pip install gcovr

ReportGenerator is available on any platform supported by .Net.

ReportGenerator can be installed via .NET Core like so:

 > dotnet tool install -g dotnet-reportgenerator-globaltool

Either or both of gcovr or ReportGenerator may be used. Only one must be installed for advanced report generation.

Enabling reporting utilities

If reports are configured (see next sections) but no :utilities: subsection exists, this plugin defaults to using gcovr for report generation.

Otherwise, enable Gcovr and / or ReportGenerator to create coverage reports.

:gcov:
  :utilities:
    - gcovr           # Use `gcovr` to create reports (default if no :utilities set).
    - ReportGenerator # Use `ReportGenerator` to create reports.

Automatic and manual report generation

By default, if reports are specified, this plugin automatically generates reports after any gcov: task is executed. To disable this behavior, add :report_task: TRUE to your project file’s :gcov: configuration.

With this setting enabled, an additional Ceedling task report:gcov is enabled. It may be executed after gcov: tasks to generate the configured reports.

For small projects, the default behavior is likely preferred. This alernative setting allows large or complex projects to execute potentially time intensive report generation only when desired.

Enabling the manual report generation task looks like this:

:gcov:
  :report_task: TRUE