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. 

Option NameDescriptionDefault
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_WORKSPACESpecifies 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_OPTSSpecifies 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:

  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.


  • No labels