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
andCPPTEST_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 – The target provided by the extension for generating 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
orc:\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 theCPPTEST_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 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
cpptest_coverage_report
target. Alternatively, you can usecpptestcli
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). Important: You must ensure the coverage log directory exists before running the instrumented application. | <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 forcpptestcli
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 theCPPTEST_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
.