# 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"
    )