This topic explains how to collect application coverage for CMake projects using the CMake extension shipped with C/C++test Standard.

Introduction

C/C++test ships with an extension for CMake that allows you to integrate C/C++test's code coverage analysis directly into your CMake project. The extension automatically modifies your compiler/linker command lines to use the cpptestcc coverage tool when building your project. As a result, after you run the instrumented application or execute functional or unit tests, a C/C++test coverage log file (.clog) is created. The coverage log file can then be used to generate a complete code coverage report.

Support for CMake integration includes:

The <CPPTEST_INSTALL_DIR>/integration/cmake/cpptest-coverage.cmake extension – The C/C++test extension file for CMake you need to add to your CMakeFiles.txt build file.
The CPPTEST_COVERAGE=ON and CPPTEST_HOME=<CPPTEST_INSTALL_DIR> options – The options provided by the extension for activating the extension when building the application with CMake.
The cpptest_coverage_report target for Make – The target provided by the extension for enabling Make to generate the coverage report using the .clog file as an input.

In addition, the <CPPTEST_INSTALL_DIR>/examples/Timer directory includes an example project to demonstrate collecting code coverage for a CMake project.

Requirements

CMake 3.10 or newer with Unix Makefiles or Ninja generator

Additional prerequisites:

Full build of the application must be performed to collect code coverage for CMake projects. Incremental builds are not supported.
On Windows, your CMake project and toolchain need to be configured for using Windows paths with forward slashes or backslashes (for example, c:/folder/source.cpp or c:\folder\source.cpp). Unix-style paths (for example, /c/folder/source.cpp) are not supported on Windows.

Workflow Overview

Copy <CPPTEST_INSTALL_DIR>/integration/cmake/cpptest-coverage.cmake to your CMake project.
Review the coverage configuration details in the cpptest-coverage.cmake file and update the options if needed. At a minimum, you must ensure that the compiler configuration specified with the CPPTEST_COMPILER_ID option matches your compiler. See Customizing the Coverage Extension for CMake for available options.
Include the cpptest-coverage.cmake extension to your main CMakeLists.txt build file. The extension must precede all build target definitions to ensure that the compiler/linker command lines are automatically modified.
Activate the extension with the CPPTEST_COVERAGE and CPPTEST_HOME options when configuring and building your CMake project:
> cmake -DCPPTEST_COVERAGE=ON -DCPPTEST_HOME=<CPPTEST_INSTALL_DIR> ..
By default, C/C++test's coverage data files will be created in <CMAKE_BINARY_DIR>/cpptest-coverage/<CMAKE_PROJECT_NAME>/.cpptest.
Run your application or execute your functional or unit tests.
By default, the C/C++test coverage log file (.clog) will be created in <CMAKE_BINARY_DIR>/cpptest-coverage/<CMAKE_PROJECT_NAME>/<CMAKE_PROJECT_NAME>.clog.
Run Make with the cpptest_coverage_report helper target to generate the coverage report:
> make cpptest_coverage_report
The coverage report will be generated in the following location: <CMAKE_BINARY_DIR>/cpptest-coverage/<CMAKE_PROJECT_NAME>/reports.
We recommend generating the coverage report using the Make target. Alternatively, you can use cpptestcli with the Coverage test configuration and the .clog file as an input:
> cd <CMAKE_BINARY_DIR>/cpptest-coverage/<CMAKE_PROJECT_NAME> > cpptestcli -config "builtin://Coverage" -input <CMAKE_PROJECT_NAME>.clog

Customizing the Coverage Extension for CMake

To customize collecting coverage with the C/C++test extension, open the cpptest-coverage.cmake file you copied to your CMake project and modify the C/C++test options.

Option Name	Description	Default
CPPTEST_COMPILER_ID	Specifies the compiler configuration that matches your compiler.	gcc_9-64
CPPTEST_COVERAGE_TYPE_FLAGS	Specifies the coverage type. See Command Line Reference for cpptestcc for available options.	-optimized-line-coverage
CPPTEST_COVERAGE_WORKSPACE	Specifies the path to the workspace for the coverage tool where C/C++test's coverage data files are stored by default.	<CMAKE_BINARY_DIR>/cpptest-coverage/<CMAKE_PROJECT_NAME>
CPPTEST_COVERAGE_LOG_FILE	Specifies the name and location of the C/C++test coverage log file (.clog).	<CPPTEST_COVERAGE_WORKSPACE>/<CMAKE_PROJECT_NAME>.clog
CPPTEST_CPPTESTCC_OPTS	Specifies the options for the `cpptestcc` coverage tool.

In addition, you may want to review:

the definition of cpptest_coverage_report target that specifies the parameters for cpptestcli for generating the coverage report.
the # Build C/C++test coverage runtime library section, which includes configuration for the C/C++test’s runtime library (the library is automatically built by the coverage extension).
the CPPTEST_LINKER_FLAGS option, which defines how the C/C++test coverage runtime will be linked.

Example of Integrating the Coverage Extension with CMake

This section demonstrates how to use C/C++test's coverage extension for CMake to collect coverage data for the example project located in the <CPPTEST_INSTALL_DIR>/examples/Timer directory. The Timer project is configured to use the cpptest-coverage.cmake extension shipped in <CPPTEST_INSTALL_DIR>/integration/cmake.

To collect coverage for the example project:

If you use a compiler other than the default GNU GCC 9 (x64), go to <CPPTEST_INSTALL_DIR>/integration/cmake/cpptest-coverage.cmake and modify the default value of the CPPTEST_COMPILER_ID to match your compiler.

Build the example project:

> cd <CPPTEST_INSTALL_DIR>/examples/Timer
> mkdir build
> cd build
> cmake -DCPPTEST_COVERAGE=ON -DCPPTEST_HOME=<CPPTEST_INSTALL_DIR> ..
> make

Run the application:
> ./timer
Generate the coverage report:
> make cpptest_coverage_report
The report will be created in <CPPTEST_INSTALL_DIR>/examples/Timer/build/cpptest-coverage/Timer/reports.