CScanner 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 Squish 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++, …) 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 alternatively 'native compiler name'+-cs. (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.

   Example:

               csg++ source.cpp -o application.exe

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

   Squish 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.

   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 COVERAGESCANNER_ARGS environment variable:

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

   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.

   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 compilers that are currently supported see Chapter (see Supported compilers). For a description of the profile syntax see Chapter (see CoverageScanner Adaptation to a Tool Suite).