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 – 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 or c:\folder\source.cpp). Unix-style paths (for example, /c/folder/source.cpp) are not supported on Windows.

Workflow Overview

1. Copy <CPPTEST_INSTALL_DIR>/integration/cmake/cpptest-coverage.cmake to your CMake project.

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

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

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

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

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

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:

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

2. Build the example project:
   

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

3. Run the application:
   

   > ./timer

4. Generate the coverage report:
   

   > make cpptest_coverage_report

   The report will be created in <CPPTEST_INSTALL_DIR>/examples/Timer/build/cpptest-coverage/Timer/reports.