Introduction

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

Prerequisites

• C/C++test for Linux (Windows is not supported)
• Bazel version 4.0+

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

A clean installation of C/C++test will not immediately work as a Bazel local repository. Follow the procedure below to add a C/C++test 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 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 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 a BDF File

1. Run the "@cpptest//:bdf" rule to generate a BDF file.
   

   bazel run @cpptest//:bdf --@cpptest//:target=//:hello-world --@cpptest//:compiler-config=gcc_10-64 --@cpptest//:project-name=HelloWorld

   A BDF file will be generated at the root of your project.

2. Run the analysis with the generated BDF file.

   cpptestcli -config "builtin://Recommended Rules" -module . -input HelloWorld.bdf -compiler gcc_10-64

   • Generating a BDF will not produce any project artifacts, i.e. executables, objects, generated sources.
   • The auto-generated code for the project will be located in the bazel-build subdirectory.
   • bazel clean will remove the contents of this directory and invalidate the BDF.
   • Rebuilding the target should resolve missing references within the BDF.

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

   • The executable generated will be of the form "<TARGET_NAME>.elf" and will be located in the bazel-bin directory next to where a binary would typically be generated. In the above example, it will be "hello-world.elf". (The use of the file extension ".elf" is arbitrary.)
   • The integration will not run the instrumented executable.

2. Execute the instrumented binary.

   ./bazel-bin/hello-world.elf

3. Generate a coverage report.

   cpptestcli -config builtin://Coverage -module . -input cpptest_results.clog

Note:

• If you are experiencing issues with memory allocation, see What if memory is not allocated when using C/C++test with a Bazel build?.
• Coverage for third party and external sources may not be displayed in IDEs (e.g. VSCode).
• When generating a coverage report for a Bazel project, C/C++test will resolve symbolic links in the file paths. To keep the symbolic links unresolved, define the following environment variable before generating the coverage report:

  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

"@cpptest//:bdf" Rule Arguments

"@cpptest//:coverage" Rule Arguments