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

Introduction

C/C++test CT 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 <INSTALL_DIR>/integration/cmake/cpptest-coverage.cmake extension – The C/C++test CT extension file for CMake you need to add to your CMakeFiles.txt build file.
  • The CPPTEST_COVERAGE=ON and CPPTEST_HOME=<INSTALL_DIR> options – The options provided by the extension for activating the extension when building the application with CMake.
  • The cpptestcov-compute, cpptestcov-report, cpptestcov-suppress targets – The targets provided by the extension for generating the coverage reports using the .clog file as an input.

In addition, the <INSTALL_DIR>/examples/CovApplication 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.

Workflow Overview

  1. Copy <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=<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 cpptestcov-compute helper target to generate the coverage data files:

    make cpptestcov-compute
    By default, the coverage data files will be generated in the following location: <CMAKE_SOURCE_DIR>/.coverage.

  7. Optionally, run the cpptestcov-suppress helper target to apply coverage suppressions to coverage data files:

    make cpptestcov-suppress

  8. Run the cpptestcov-report helper target to generate the the coverage report files:

    make cpptestcov-report
    By default, the coverage report files will be generated in the following location: <CMAKE_SOURCE_DIR>/.coverage.

Customizing the Coverage Extension for CMake

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

Option NameDescription

Default

CPPTEST_COMPILER_ID

Specifies the compiler configuration that matches your compiler.

gcc_10-64
CPPTEST_COVERAGE_TYPE_INSTRUMENTATIONSpecifies the coverage types to be enabled for code instrumentation. See Command Line Reference for cpptestcc for available options.-line-coverage -statement-coverage -block-coverage -decision-coverage -simple-condition-coverage -mcdc-coverage -function-coverage -call-coverage
CPPTEST_COVERAGE_TYPE_REPORTSpecifies the coverage types to be enabled for report generation.LC,SC,BC,DC,SCC,MCDC,FC,CC
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.

Example of Integrating the Coverage Extension with CMake Project

This example uses C/C++test CT coverage extenstion for CMake.

  1. Go to <INSTALL_DIR>/examples/CovApplication

  2. Create a build directory.
    mkdir .build
  3. Configure and build the project with coverage enabled.
    cd .build
cmake -DCPPTEST_COVERAGE=ON -DCPPTEST_HOME=$PWD/../../.. .. 
make
  4. Execute the instrumented application.
    ./timer
  5. Generate coverage data files into .coverage/lastrun.  
    make cpptestcov-compute
  6. Merge .coverage/lastrun into .coverage/cumulative. 
    make cpptestcov-merge
  7. Apply coverage suppressions for .coverage/cumulative. 
    make cpptestcov-suppress
  8. Report coverage statistics for .coverage/cumulative.  
    make cpptestcov-report


  • No labels

Need assistance? Visit our support page