CoverageScanner introduction

CoverageScanner is a C++ program that—in effect—replaces the usual compiler. It uses the native compiler's preprocessor program to process the source code, then inserts instrumentation code into the preprocessed program, and at the end it compiles and links the project file, in the same way as in a normal build.

CoverageScanner's instrumentation process consists of:

1. declaring a static table that contains the instrumentation results.
2. generating a library which produces an execution report when the program terminates or receives a UNIX^® signal or a Microsoft^® Windows event.
3. adding the instrumentation code itself for each relevant statement or Boolean expression.

The compiler, linker and preprocessor that are used are from the native environment (gcc, Visual Studio, etc.). The Coco tools are used transparently and the developer has only to prepend cs to the name of the compiler executable to activate the code coverage. For example, using csgcc instruments the source code and uses the gcc compiler to generate objects.

Another way to achieve coverage is to add a wrapper directory to the search path. It contains compiler wrappers with the same name as the native tools. They are disabled by default but can be switched on with help of the COVERAGESCANNER_ARGS environment variable.

Invoking CoverageScanner

CoverageScanner works like a preprocessor which calls the native compiler (Microsoft cl.exe, GNU g++, and so on) after instrumenting a source file.

Several invocation methods are possible:

1. Using a dedicated CoverageScanner executable for a specific compiler: CoverageScanner executable for a specific compiler is named cs-<native compiler name> or <native compiler name-cs. For example, cl.exe is the Microsoft C++ compiler and the corresponding CoverageScanner executable is cscl.exe or cl-cs.exe.

   CoverageScanner aims to work like the native compiler with the difference that the code get instrumented.

   For example:

   csg++ source.cpp -o application.exe

2. Using CoverageScanner compiler wrapper and activating the instrumentation using --cs-on in the command line arguments:

   Coco provides a replacement of the native compiler called wrapper which extends its command line arguments to support the code coverage feature. To use it, add to the first position of the PATH variable, the path of the CoverageScanner wrapper. The instrumentation gets activated when adding --cs-on to the command line argument.

   For example:

   export PATH=/opt/SquishCoco/wrapper/bin:$PATH
   g++ --cs-on source.cpp -o application.exe

   Or, without modifying globally the PATH variable:

   PATH=/opt/SquishCoco/wrapper/bin:$PATH g++ --cs-on source.cpp -o application.exe

3. Using CoverageScanner compiler wrapper and activating the instrumentation through the COVERAGESCANNER_ARGS environment variable:

   It is also possible to set the command line arguments of the wrapper using the COVERAGESCANNER_ARGS environment variable. In this case it is no longer necessary to modify the command line arguments.

   For example:

   export PATH=/opt/SquishCoco/wrapper/bin:$PATH
   export COVERAGESCANNER_ARGS='--cs-on'
   g++ source.cpp -o application.exe

   Or, to instrument a complete project built using GNU make:

   COVERAGESCANNER_ARGS='--cs-on' PATH=/opt/SquishCoco/wrapper/bin:$PATH make all

4. Using --cs-compiler command line option of CoverageScanner:

   --cs-compiler specifies which native compiler should be used. All other command line arguments, except those specific to CoverageScanner, are passed through to the native compiler.

   For example:

   coveragescanner --cs-compiler=g++ source.cpp -o application.exe

Compiler support is done with the help of a profile. It contains declarations which make it possible to adapt CoverageScanner to C, C++ and C# preprocessors, compilers and linkers. For a description of the profile syntax see CoverageScanner adaptation to a tool suite.