CTestCoverageCollectGCOV

Added in version 3.2.

This module is intended for use in CTest dashboard scripts and provides a command to generate a tarball containing code coverage reports.

Load this module in a CTest script with:

include(CTestCoverageCollectGCOV)

Commands

This module provides the following command:

ctest_coverage_collect_gcov

Runs gcov and packages a tar file for CDash:

ctest_coverage_collect_gcov(
  TARBALL <tar-file>
  [TARBALL_COMPRESSION <compression>]
  [SOURCE <source-dir>]
  [BUILD <build-dir>]
  [GCOV_COMMAND <gcov-command>]
  [GCOV_OPTIONS <options>...]
  [GLOB]
  [DELETE]
  [QUIET]
)

This command runs gcov on all .gcda files found in the binary tree and packages the resulting .gcov files into a tar file, along with the following:

  • data.json file that defines the source and build directories for use by CDash.

  • Labels.json files that indicate any LABELS that have been set on the source files.

  • The uncovered directory containing any uncovered files found by CTEST_EXTRA_COVERAGE_GLOB.

The resulting tar file can be submitted to CDash for display using the ctest_submit(CDASH_UPLOAD) command.

The arguments are:

TARBALL <tar-file>

Specify the location of the .tar file to be created for later upload to CDash. Relative paths will be interpreted with respect to the top-level build directory.

TARBALL_COMPRESSION <compression>

Added in version 3.18.

Specify a compression algorithm for the TARBALL data file. Using this option reduces the size of the data file before it is submitted to CDash. <compression> must be one of GZIP, BZIP2, XZ, ZSTD, FROM_EXT, or an expression that CMake evaluates as FALSE. The default value is BZIP2.

If FROM_EXT is specified, the resulting file will be compressed based on the file extension of the <tar-file> (i.e. .tar.gz will use GZIP compression). File extensions that will produce compressed output include .tar.gz, .tgz, .tar.bzip2, .tbz, .tar.xz, and .txz.

SOURCE <source-dir>

Specify the top-level source directory for the build. Default is the value of CTEST_SOURCE_DIRECTORY.

BUILD <build-dir>

Specify the top-level build directory for the build. Default is the value of CTEST_BINARY_DIRECTORY.

GCOV_COMMAND <gcov-command>

Specify the full path to the gcov command on the machine. Default is the value of CTEST_COVERAGE_COMMAND.

GCOV_OPTIONS <options>...

Specify options to be passed to gcov. The gcov command is run as gcov <options>... -o <gcov-dir> <file>.gcda. If not specified, the default option is just -b -x.

GLOB

Added in version 3.6.

Recursively search for .gcda files in <build-dir> rather than determining search locations by reading CMakeFiles/TargetDirectories.txt (file generated by CMake at the generation phase).

DELETE

Added in version 3.6.

Delete coverage files after they've been packaged into the .tar.

QUIET

Suppress non-error messages that otherwise would have been printed out by this command.

Added in version 3.3: Added support for the CTEST_CUSTOM_COVERAGE_EXCLUDE variable.

Examples

Generating code coverage data packaged as a .tar.gz file in a ctest -S script:

script.cmake
include(CTestCoverageCollectGCOV)

ctest_coverage_collect_gcov(
  TARBALL "${CTEST_BINARY_DIRECTORY}/gcov.tar.gz"
  TARBALL_COMPRESSION "GZIP"
)