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

Note: For Microsoft® Visual Studio®, an additional wrapper is provided which directly uses the Microsoft® ’cl’ and ’link’ (see Microsoft® Visual Studio®)

. 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

Note: The native compiler path needs to appear in the PATH variable, after the path to the compiler wrappers. This is necessary for finding the location of the native compiler after insertion of the instrumentation code.

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

© 2022 The Qt Company Ltd. Documentation contributions included herein are the copyrights of their respective owners. The documentation provided herein is licensed under the terms of the GNU Free Documentation License version 1.3 as published by the Free Software Foundation. Qt and respective logos are trademarks of The Qt Company Ltd. in Finland and/or other countries worldwide. All other trademarks are property of their respective owners.