Introduction

This section describes how to integrate C/C++test CT with a Bazel build for running static analysis and code coverage.

Prerequisites

Adding a C/C++test CT Installation as a Bazel Local Repository

A clean installation of C/C++test CT will not immediately work as a Bazel local repository. Follow the procedure below to add a C/C++test CT installation as a Bazel local repository.

  1. Move the WORKSPACE.bazel and BUILD.bazel files located in the integration/bazel directory to the root of the C/C++test CT installation.
    cd <INSTALL_DIR>
mv integration/bazel/WORKSPACE.bazel .
mv integration/bazel/BUILD.bazel .
    Note: Make sure the files are moved and no copy remains in the integration/bazel directory.
  2. Open the Bazel WORKSPACE file at the root of your project.

  3. Register the C/C++test CT installation as a Bazel local repository in your WORKSPACE file.

    local_repository(name = "cpptest", path = "<INSTALL_DIR>")

Example Build Target

The following example will be used in the subsequent procedures:

cc_binary(
    name = "hello-world",
    srcs = ["hello-world.cc"],
    deps = [
        ":hello-greet",
    ],
)

Generating an Executable with Code Coverage

Follow the procedure below to generate a test binary with code coverage instrumentation. 

  1. Run the "@cpptest//:coverage" rule to generate the instrumented binary.

    bazel run @cpptest//:coverage --@cpptest//:target=//:hello-world --@cpptest//:compiler-config=gcc_10-64 --@cpptest//:line-coverage

  2. Execute the instrumented binary.

    bazel-bin/hello-world.elf

  3. Generate coverage data files.

    cpptestcov compute -map .cpptest -clog cpptest_results.clog -out .coverage

  4. Generate a coverage report.

    cpptestcov report text .coverage

Note: When generating coverage data for a Bazel project, C/C++test CT will resolve symbolic links in the file paths. To keep the symbolic links unresolved, define the following environment variable before generating the coverage data files.

export CPPTEST_COVERAGE_SRC_ROOT_RESOLVE_SYMLINKS=false

Configuring the Coverage Instrumentation Tool (cpptestcc) 

You can configure the coverage instrumentation tool (cpptestcc) using a .psrc configuration file.

  1. Copy the example .psrc file to the project.

    cp <INSTALL_DIR>/integration/bazel/cpptestcc-bazel.psrc <PROJECT_ROOT>/cpptestcc-bazel.psrc
  2. Modify the contents of cpptestcc-bazel.psrc, as needed. For a list of options, see Command Line Reference for cpptestcc or run:
    cpptestcc -help

  3. Define the "cpptestcc-bazel-psrc" filegroup in your BUILD.bazel file that refers to the cpptestcc-bazel.psrc file.

    filegroup(name = "cpptestcc-bazel-psrc", srcs = ["cpptestcc-bazel.psrc"], visibility = ["//visibility:public"])

  4. Use the "--@cpptest//:psrc_file" option with the "cpptestcc-bazel-psrc" filegroup when executing the "@cpptest//:coverage" rule.

    bazel run @cpptest//:coverage --@cpptest//:target=//:hello-world --@cpptest//:psrc_file=//:cpptestcc-bazel-psrc

Configuration Options for C/C++test's Bazel Rules

Common Arguments

Option

Description

--@cpptest//:target=<TARGET>

Specifies the target rule to be analyzed. A project rule of the type "cc_*" or a type derived from it should be specified.
Default: None
Example: --@cpptest//:target=//main:hello-world

--@cpptest//:psrc_file=<CUSTOM_PSRC_FILEGROUP>

Specifies the filegroup for the .psrc configuration file; see Configuring the Coverage Instrumentation Tool (cpptestcc).
Default: None
Example: --@cpptest//:psrc_file=//:cpptestcc-bazel-psrc

Before using this option, be sure to define the filegroup that refers to the .psrc configuration file in your BUILD.bazel file. For example:
filegroup(name = "cpptestcc-bazel-psrc", srcs = ["cpptestcc-bazel.psrc"], visibility = ["//visibility:public"])
See the <INSTALL_DIR>/integration/bazel/cpptestcc-bazel.psrc file for more information.

"@cpptest//:coverage" Rule Arguments

Option

Description

--@cpptest//:compiler-config=<COMPILER_CONFIGURATION_NAME>

Specifies the compiler configuration.
This argument is mandatory unless the compiler configuration is specified in the .psrc file; see Configuring the Coverage Instrumentation Tool (cpptestcc).
Default: None
Example: --@cpptest//:compiler-config=clang_12_0

--@cpptest//:line-coverage
--@cpptest//:optimized-line-coverage
--@cpptest//:function-coverage
--@cpptest//:optimized-function-coverage
--@cpptest//:statement-coverage
--@cpptest//:optimized-statement-coverage
--@cpptest//:block-coverage
--@cpptest//:optimized-block-coverage
--@cpptest//:simple-condition-coverage
--@cpptest//:optimized-simple-condition-coverage
--@cpptest//:decision-coverage
--@cpptest//:optimized-decision-coverage
--@cpptest//:call-coverage
--@cpptest//:optimized-call-coverage

--@cpptest//:mcdc-coverage

Enables specific coverage metric(s).

This is mandatory unless it is specified in the .psrc file; see Configuring the Coverage Instrumentation Tool (cpptestcc).

--@cpptest//:verbose

Enables verbose console output for all stages of cpptestcc instrumentation and compilation.
Default: False

--@cpptest//:quiet

Suppresses all console text output from the cpptest engine during execution.
Default: False

Example of Integrating with Bazel Project

This example uses C/C++test CT coverage plugin for Bazel.

  1. Move <INSTALL_DIR>/integration/bazel/WORKSPACE.bazel and <INSTALL_DIR>/integration/bazel/BUILD.bazel into the C/C++test CT installation directory. 
    Note: Make sure the files are moved and no copy remains in the integration/bazel directory.
  2. Go to <INSTALL_DIR>/examples/CovApplication
  3. Build the project with coverage enabled.
    bazel run --config=cpptest_coverage
  4. Execute the instrumented application.
    bazel-bin/Timer.elf
  5. Generate coverage data files into .coverage.
    cpptestcov compute -map .cpptest -clog cpptest_results.clog -out .coverage
  6. Report coverage statistics for .coverage.
    cpptestcov report text .coverage

See <INSTALL_DIR>/integration/bazel/README.txt for more details.