In this section:

Instrumenting and Building Source Code

Three steps are performed during this phase:

1. Source code is instrumented.
2. Instrumented source code is compiled to the object file.
3. All instrumented and non-instrumented objects are linked to the code coverage tool library, as well as any additional libraries required to form the final testable binary artifact.

These steps are typically performed during the build process and require that the coverage tool be integrated with the user build system. The cpptestcc tool instruments the source code and compiles it into the object file. The cpptestcc is designed to be used as a compiler prefix in compilation command lines.

Original compilation command line: 

cc -I app/includes -D defines -c source.cpp

Coverage mode compilation command line:  

cpptestcc -compiler gcc_3_4 -line-coverage -workspace /home/test/proj/cov -- cc -I app/includes -D defines -c source.cpp

When the coverage mode compilation command line is executed, cpptestcc performs the following operations:

• Compilation command line is analyzed to extract information about source files
• All detected source files are parsed and instrumented for coverage metrics
• Instrumented files are reconstructed in the specified location using the -workspace switch; additional information about the code structure used during report generation is also stored
• Compilation command line is modified and the original source files are substituted with instrumented versions
• Compilation command line is executed, object(s) files are created in the same location as in case of original command line

You can add the [INSTALL_DIR]/bin directory to your PATH variable so that you do not have to use full paths when specifying the cpptestcc command. All examples in this documentation assume this has been done.

The following pattern describes the syntax for coverage instrumentation:

cpptestcc -compiler <compiler configuration> <coverage metric specification> -workspace <workspace directory> -- <compilation command line>

• <compiler configuration> refers to a supported compiler configuration, e.g., gcc_3_4; see Supported Compilers for the list of supported compilers.
• <coverage metric specification> refers to a supported coverage metric, e.g., line-coverage. See Command Line Reference for cpptestcc for the list of supported coverage metrics.
• The cpptestcc command line is separated from compiler command line with the -- separator.

Linking Instrumented Code

The original linker command must be modified to include the additional library required by the code coverage instrumentation. The following example shows how this is typically accomplished:

Original compilation command line:  

lxx -L app/lib app/source.o -lsomelib -o app.exe

Coverage mode compilation command line: 

lxx -L app/lib app/source.o somelib.lib <coverage tool>/runtime/lib/cpptest.lib -o app.exe

Executing Instrumented Code 

Details of the execution environment depend on the application specifics, but the coverage tool imposes the following limited dependencies on execution:

• If the coverage tool library was linked as a shared (dynamic-load) library, then you must ensure that the library can be loaded when instrumented application is started. On Windows, this typically requires adding [INSTALL_DIR]/bin directory to the PATH environment variable. On Linux systems, add [INSTALL_DIR]/runtime/lib to the LD_LIBRARY_PATH variable.
• If the coverage results transport channel was modified, all requirements resulting from the modification have to be fulfilled. For example, if results are sent through TCP/IP socket or rs232 then appropriate listening agents need to be started before the instrumented application executes.

After the instrumented application finishes execution, the collected results must be stored in the file that will be used for report generation.

Generating Reports

Final coverage report is generated from two types of information:

• Code structure information generated by cpptestcc during build process (stored in workspace)
• Coverage results achieved from instrumented code execution

Coverage report can be generated in an HTML format or sent to DTP Server. The following example shows the command for generating a report:

cpptestcli -config builtin://Coverage -input cpptest_results.clog -workspace /home/test/proj/cov

In order to properly merge coverage data in DTP, you must specify one or more coverage image tags in the command line or .properties settings file. The coverage image(s) is automatically sent to the connected DTP server where it can be associated with a filter.

You can specify a set of up to three tags that can be used to create coverage images in DTP Server with the report.coverage.images property:

report.coverage.images=[tag1; tag2; tag3]

Associate coverage images in DTP in the Report Center administration page (administration> Projects> Filters> [click on a filter]).

You can also use the report.coverage.limit property to specify a lower coverage threshold:

report.coverage.limit=[value]

Coverage results lower than this value are highlighted in the report. The default value is 40. 

Usage Example

In this example, the following code is from a c++ source file called main.c: 

#include <iostream>

int main(int argc, char ** argv) {
   if (argc > 1) {
      std::cout << "Thank you for arguments" << std::endl;
   } else {
      std::cout << "Provide some arguments please !" << std::endl;
   }
   return 0;
}

The normal file compilation command is gcc: 

g++ -c main.c -o main.o

To instrument this file and compile the instrumented code to the object file, the compilation command line must include the cpptestcc command prefix: 

cpptestcc -compiler gcc_3_4 -line-coverage -workspace /home/test/proj/cov -- g++ -c main.c -o main.o

Two artifacts are created as s a result of the cpptestcc command invocation:

• an object with instrumented code
• code structure information stored in the directory specified with -workspace option

Once the source file is instrumented and compiled to the object file it, can be linked to form the final executable. Normally this simple example would be linked with the following command:

g++ main.o -o app.exe

Coverage instrumentation requires additional library so the linking command line needs to look as follows:

g++ main.o <coverage tool install dir>/runtime/lib/cpptest.a -o app.exe

In this example, the static version of the coverage library was used. The dynamic/shared version, as well as the source code, is also provided for building a customized version. For additional information, see Code Coverage Runtime Library.

Once the application is linked it can be executed to collect information about code coverage. Run the following command:

./app.exe

The application will output the coverage log file, named cpptest_results.clog by default, in the current work directory.

Finally, generate the report using the following command:  

cpptestcli -config builtin://Coverage -workspace /home/test/proj/cov -input cpptest_results.clog -report report_dir

A report directory will be created containing the HTML report with code coverage information.