Code Coverage for the CMake Build System

Use this guide to generate code coverage for a project that uses the CMake build system. The workflow is the same idea RKTracer uses everywhere: you prefix the rktracer command to your existing build, and RKTracer instruments the code during compilation. The runtime libraries are added to the build system automatically, so you can run the instrumented application on a native host or on an embedded target and then generate the coverage report.

Step 1: Enable the RKTracer tool

Prefix the rktracer command to your CMake configure command. For example, if your original command is:

cmake -G "MinGW Makefiles" "D:\path-to-project\project"

Prefix rktracer (here with the verbose flag -v) to enable the coverage tool:

rktracer -v cmake -G "MinGW Makefiles" "D:\path-to-project\project"

RKTracer finds the compiler used in the CMake build and, based on the compiler it finds, makes the necessary changes to the CMakeCache.txt file. Now run the make command to build and instrument the project.

What happens during instrumentation

RKTracer preprocesses each source file, then instruments the preprocessed file (with the bundled librklic instrumentor) and writes out the instrumented preprocessed file to a prime.i file. It also stores the metadata, the structure of the instrumentation, and a copy of the source file content to corresponding JSON files. RKTracer refers to rktracer.config for its internal configuration at instrumentation time, and adds the runtime automatically at link time.

Step 2: Run your tests on the instrumented application

Run your tests against the RKTracer-instrumented application, on a native host or on an embedded system. As the instrumented application runs, RKTracer captures the coverage data and writes the coverage data file (rk-coverage.txt).

Step 3: Generate the HTML coverage report

Once you have the rk-coverage.txt file, run the rkresults command to generate the HTML reports. Run rkresults in the project root folder, that is, the folder that contains the rktracer folder.

rkresults

The rkresults command searches for the coverage data file rk-coverage.txt, maps it with the JSON files generated during instrumentation (in the rktracer folder), and generates the HTML reports. You can open the HTML report manually using index.html.

Enable coverage for selected files and functions

You can scope coverage to specific folders, files, or functions by editing rktracer.config.

Coverage for selected folders

For example, to instrument source files from some folders while ignoring others, given folders such as:

C:\project\sound\drivers\base\power\
C:\project\sound\drivers\base\power\firmware_loader\
C:\project\sound\drivers\core\
C:\project\sound\security\keys\
C:\project\sound\security\lockdown\

Add the following at the end of rktracer.config:

ignore *.c
instrument */power/* */core/* */keys/*
never */firmware_loader/* */lockdown/*

• ignore *.c ignores all C source files from instrumentation.
• instrument instruments source files from the given folders.
• never ignores the selected folders.

Coverage for selected functions

To generate coverage only for specific functions in specific files, edit rktracer.config:

ignore *.c
instrument *source-file-X.c *source-file-Y.c *source-file-Z.c
function-ignore *
function-instrument fun_X() fun_Y() fun_Z()

• ignore *.c ignores all C source files.
• instrument *source-file-X.c *source-file-Y.c *source-file-Z.c instruments only these three source files.
• function-ignore * then ignores all functions in the above three files.
• function-instrument fun_X() fun_Y() fun_Z() does not ignore these three functions from instrumentation.

Next steps

Once your CMake project reports coverage, the same RKTracer workflow applies across other build systems and IDEs. Browse the rest of the documentation, or read more about how RKTracer measures coverage through MC/DC.