• Overview
• Documentation
  • Code Coverage
  • Quick Start and Tutorial
  • CoverageBrowser
  • CoverageScanner
  • Command Line Tools
  • FAQ
  • Appendix
• Release Note
• License

Part IV
CoverageScanner Reference Manual

• Introduction
• Compiler Support
  • Invoking CoverageScanner
  • Supported Compilers
    • Microsoft^® Visual C++
    • Intel^® C++ Compiler
    • GNU gcc
  • IDE Support
    • GNU Makefile
    • Scratchbox
    • CMake
      • Coverage Configuration
      • Visual Studio
      • GCC
    • Qt
      • qmake
      • moc
    • Visual Studio
      • Visual Studio .NET C++ Compiler
      • Visual Studio Add-In
      • Visual C++ Express
      • Visual Studio 6.0
    • eMbedded Visual C++
    • Eclipse
    • Xcode
• Command Line
  • Synopsis
  • Instrumenting using preprocessor defines
  • C and C++ Library
    • __coveragescanner_install
    • __coveragescanner_testname
    • __coveragescanner_teststate
    • __coveragescanner_add_html_comment
    • __coveragescanner_clear_html_comment
    • __coveragescanner_save
    • __coveragescanner_clear
    • __coveragescanner_filename
    • __coveragescanner_register_library
    • __coveragescanner_unregister_library
    • __coveragescanner_set_custom_io
  • Controlling the instrumentation during the compilation
    • C and C++ Pragma
  • Regular Expressions
• Code Coverage of Libraries
  • Code Coverage of Static/Shared Libraries and DLL
  • Code Coverage of Plugins/Manually Loaded Shared Libraries
    • Code Coverage of Plugins Generated with Microsoft^® Visual Studio^®
    • Code Coverage of Plugins Generated with GNU gcc
• Test Suite and Squish Coco
  • Execution Comment, Name And Status
  • Unit Testing
  • Test Framework Support
    • CppUnit
    • QTestLib
    • GoogleTest
    • CxxTest

Chapter 22  Introduction

CoverageScanner is the application which inserts the instrumentation into the source code. It performs the following operations:

1. Runs the C preprocessor.
2. Instruments the preprocessed source code.
3. Compiles the source code using the native C or C++ compiler.

Mainly, during normal usage, it replaces the native compiler.

Chapter 23  C and C++ Compiler Support

Compiler support is carried out through a profile. A profile contains a set of declarations which makes it possible to adapt CoverageScanner to C and C++ preprocessors, compilers and linkers.

23.1  Invoking CoverageScanner

CoverageScanner works like a pre-processor which calls after instrumenting a source file the native compiler (Microsoft^® cl.exe, GNU g++, …).

Several invocation method are possible:

1. Using the dedicated CoverageScanner executable for a specific compiler:

   CoverageScanner executable for a specific compiler is called to 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 then as the native compiler with the difference that the code get instrumented.

   Example: 

           csg++ source.c -o application.exe
           

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

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

   Example: 

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

   or without modifying globally the PATH variable:

           PATH=/opt/SquishCoco/wrapper/bin:$PATH g++ --cs-on source.c -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. In this case modifying the command line argument is no more necessary.

   Example: 

           export PATH=/opt/SquishCoco/wrapper/bin:$PATH
           export COVERAGESCANNER_ARGS='--cs-on'
           g++ source.c -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 permits to select which native compiler should be used. All other command line arguments, except those specific to CoverageScanner, are passed through the native compiler.

   Example: 

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

23.2  Supported Compilers

The following compilers are currently supported by CoverageScanner:

23.2.1  Microsoft^® Visual C++

The command line compiler and linker of Microsoft^® Visual C++ and Microsoft^® Visual C++ Toolkit 2003 are supported.

23.2.2  Intel^® C++ Compiler

The C and C++ command line compiler from Intel^® is supported.

23.2.3  GNU gcc

Only g++ and gcc command line compilers are directly supported.

To implement support for GNU cross-compilers proceed as follows:

1. Copy ’coveragescanner’ to the file ’cs+<compiler name>’.
   (ex: copy coveragescanner.exe csarm-linux-gcc.exe)
2. Copy the profile ’gcc.cspro’ or g++.cspro’ to ’<compiler name>+.cspro’.
   (ex: copy gcc.cspro arm-linux-gcc.cspro)
3. Edit the new profile and set the parameter TOOL to ’<compiler name>’.
   (ex: TOOL=arm-linux-gcc)
4. The new GNU cross-compiler ’cs+<compiler name>’ can now be used. It inserts the instrumentations and calls the ’<compiler name>’ for compilation.

23.3  Integrated Development Environment Support

23.3.1  GNU Makefile

Mostly, in makefiles, the C and C++ compiler and the linker are defined using the environment variable CC, CXX and LINK. This can be substituted by CoverageScanner by setting CC, CXX and LINK in the command arguments of make.


Example: make LINK=csg++ CXX=csg++ CC=csgcc

23.3.2  Scratchbox

If Squish Coco is installed on the root file system¹, a compiler wrapper is created for each compiler supported by Scratchbox. To invoke CoverageScanner, prepend cs to the name of the cross-compiler.

23.3.3  Kitware CMake

CMake is a platform independent build tool from Kitware which can be downloaded from http://www.cmake.org.

Coverage Configuration

Create a new CMake COVERAGE configuration by adding in CMakeLists.txt following lines:

SET(COVERAGE_FLAGS "--cs-on --cs-count")
SET( CMAKE_CXX_FLAGS_COVERAGE 
     "${CMAKE_C_FLAGS_RELEASE} ${COVERAGE_FLAGS}" CACHE STRING
    "Flags used by the C++ compiler during coverage builds."
    FORCE )
SET( CMAKE_C_FLAGS_COVERAGE 
     "${CMAKE_CXX_FLAGS_RELEASE} ${COVERAGE_FLAGS}" CACHE STRING
    "Flags used by the C compiler during coverage builds."
    FORCE )
SET( CMAKE_EXE_LINKER_FLAGS_COVERAGE
    "${CMAKE_EXE_LINKER_FLAGS_RELEASE} ${COVERAGE_FLAGS}" CACHE STRING
    "Flags used for linking binaries during coverage builds."
    FORCE )
SET( CMAKE_SHARED_LINKER_FLAGS_COVERAGE
    "${CMAKE_SHARED_LINKER_FLAGS_RELEASE} ${COVERAGE_FLAGS}" CACHE STRING
    "Flags used by the shared libraries linker during coverage builds."
    FORCE )
SET( CMAKE_STATIC_LINKER_FLAGS_COVERAGE
    "${CMAKE_STATIC_LINKER_FLAGS_RELEASE} ${COVERAGE_FLAGS}" CACHE STRING
    "Flags used by the static libraries linker during coverage builds."
    FORCE )
MARK_AS_ADVANCED(
    CMAKE_CXX_FLAGS_COVERAGE
    CMAKE_C_FLAGS_COVERAGE
    CMAKE_EXE_LINKER_FLAGS_COVERAGE
    CMAKE_SHARED_LINKER_FLAGS_COVERAGE 
    CMAKE_STATIC_LINKER_FLAGS_COVERAGE 
    COMPILE_DEFINITIONS_COVERAGE
)

Use the variable COVERAGE_FLAGS to specify CoverageScanner command line options.

Microsoft^® Visual Studio^®

Proceed as follows:

1. Create toolchain definition file called cl.cmake which set the path of the compiler and linker to CoverageScanner wrapper.
   Example: 

   # this one is important
   SET(CMAKE_SYSTEM_NAME Windows)
   
   # specify the cross compiler
   FILE(TO_CMAKE_PATH "$ENV{SQUISHCOCO}/visualstudio" SQUISHCOCO)
   SET(CMAKE_C_COMPILER ${SQUISHCOCO}/cl.exe 
       CACHE FILEPATH "CoverageScanner wrapper" FORCE)
   SET(CMAKE_CXX_COMPILER ${SQUISHCOCO}/cl.exe 
       CACHE FILEPATH "CoverageScanner wrapper" FORCE)
   SET(CMAKE_LINKER ${SQUISHCOCO}/link.exe 
       CACHE FILEPATH "CoverageScanner wrapper" FORCE)
   

2. Create a Makefile project and set the toolchain to CoverageScanner wrapper and the build mode to COVERAGE.
   Example: 

   cmake.exe -DCMAKE_TOOLCHAIN_FILE=cl.cmake -DCMAKE_BUILD_TYPE=COVERAGE 
             -G "NMake Makefiles" <path_of_cmake_project>
   

3. Build the project using nmake.

GNU GCC

1. Create toolchain definition file called gcc.cmake which set the path of the compiler and linker to CoverageScanner.
   Example: 

   find_program(CODE_COVERAGE_GCC csgcc)
   find_program(CODE_COVERAGE_GXX csgxx)
   find_program(CODE_COVERAGE_AR csar)
    
   # specify the cross compiler
   SET(CMAKE_C_COMPILER "${CODE_COVERAGE_GCC}"
       CACHE FILEPATH "CoverageScanner wrapper" FORCE)
   SET(CMAKE_CXX_COMPILER "${CODE_COVERAGE_GXX}"
       CACHE FILEPATH "CoverageScanner wrapper" FORCE)
   SET(CMAKE_LINKER "${CODE_COVERAGE_GXX}"
       CACHE FILEPATH "CoverageScanner wrapper" FORCE)
   SET(CMAKE_AR "${CODE_COVERAGE_AR}"
       CACHE FILEPATH "CoverageScanner wrapper" FORCE)
   

2. Create a Makefile project and set the toolchain to CoverageScanner and the build mode to COVERAGE.
   Example: 

   cmake.exe -DCMAKE_TOOLCHAIN_FILE=gxx.cmake -DCMAKE_BUILD_TYPE=COVERAGE 
             -G "Unix Makefiles" <path_of_cmake_project>
   

3. Build the project using make.

23.3.4  Qt Library from Nokia

Nokia qmake

The variables QMAKE_CC, QMAKE_CXX and QMAKE_LINK contain the name of the C compiler, the C++ compiler and the linker command line used by qmake to generate the makefiles. This variable can be set as a command line argument of qmake.


Example: qmake QMAKE_LINK=cslink QMAKE_CXX=cscl QMAKE_CC=cscl

An other alternative is to create a configuration called CodeCoverage in the .pro file:

CodeCoverage {
  QMAKE_CXX=cs$$QMAKE_CXX
  QMAKE_CC=cs$$QMAKE_CC
  QMAKE_LINK=cs$$QMAKE_LINK
}

Calling qmake CONFIG+=CodeCoverage will generate the makefiles with code coverage activated.

Nokia Meta-Object Compiler (moc)

Nokia Meta-Object Compiler add automatically in each classes derived from QObject new methods. For example, the translation function tr, the source code for all signals, the cast operator qt_cast, …In order to instrument the code using the Qt Library and not the library itself, CoverageScanner provides the command line options --cs-qt4 for Qt4 (resp. --cs-qt3 for Qt3).
In this case:

• Q_OBJECT macro is no more instrumented.
• All signal are instrumented in order to track their emission.
• The glue code necessary for the signal/slot mechanism is not instrumented.
• The code of Q_FOREACH macro is not instrumented on Qt4.

23.3.5  Microsoft^® Visual Studio^®

Squish Coco provides a wrapper for link.exe and cl.exe located on the %SQUISHCOCO%\visualstudio directory. It behaves exactly like the corresponding Microsoft^® wrapper except that the code coverage analysis becomes activated when the option --cs-on is added to the command arguments. These wrappers call the Microsoft^® tools for compilation or for linkage.

Microsoft^® Visual Studio^® .NET C and C++ Compiler

To use Squish Coco with Microsoft^® Visual Studio^® .NET proceed as follows:

1. Add the location of the CoverageScanner wrappers to the first position in the VC++ Directories.
   For Microsoft^® Visual Studio^® 2005 or 2008:
   1. Start Microsoft^® Visual Studio^® 2005 or 2008.
   2. Open the option dialog: click on "Tools->Preferences…".
   3. Select the item "Projects->VC++ Directories".
   4. Add the entry $(SQUISHCOCO)\visualstudio to the first position in the list of directories. (see figure fig:visual_option_net_fig)

      Installation of CoverageScanner on Microsoft® Visual Studio® 2005 and 2008: Setting the path of CoverageScanner. Installation of CoverageScanner on Microsoft® Visual Studio® 2005 and 2008: Setting the path of CoverageScanner.

   For Microsoft^® Visual Studio^® 2010:

   1. Start Microsoft^® Visual Studio^® 2010.
   2. Open a C++ project.
   3. Open the project properties using the context menu of the laded project.
   4. Select the item "Configuration Properties->VC++ Directories".
   5. Add the entry $(SQUISHCOCO)\visualstudio to the first position in the list of executable directories. (see figure fig:visual_option_vs2010_fig)

      Installation of CoverageScanner on Microsoft® Visual Studio® 2010: Setting the path of CoverageScanner. Installation of CoverageScanner on Microsoft® Visual Studio® 2010: Setting the path of CoverageScanner.

2. To activate code coverage analysis:
   1. Open a Visual C or C++ project.
   2. Edit the project settings (click on "Project->Properties").
   3. Add to the option --cs-on to the additional command line arguments of the C or C++ compiler and linker. (see figure fig:visual_compiler_net_fig)
   4. In the additional arguments of the linker, add the --cs-libgen which permits to specify which library should be used for the generation of the CoverageScanner library. The table tab:librarysettings contains the list of recommended settings.
   5. For Microsoft^® Windows CE applications, append to the linker arguments the command line option --cs-architecture which permits to specify the target platform. The table tab:architectures contains the list of available architectures.

Activation of the instrumentation under Visual Studio® .NET. Activation of the instrumentation under Visual Studio® .NET.

Activation of the instrumentation under Visual Studio® .NET. Activation of the instrumentation under Visual Studio® .NET.

Squish Coco Add-In for Microsoft^® Visual Studio^® 2005, 2008 and 2010

Squish Coco provides for Microsoft^® Visual Studio^® 2005, 2008 and 2010 an Add-In which does automatically the steps described in the section visualstudiodotnet. The Add-In itself is normally not mandatory to build an instrumented application.

To use it:

1. Open a C++ project.
2. Click on Tools->Code Coverage Build Mode….
3. Select the base configuration and the project which should be compiled with code coverage support.
4. Click on Enable code coverage to generate a new build mode with code coverage support. Disable code coverage removes all CoverageScanner command line options.

Microsoft® Visual Studio® Add-In Microsoft® Visual Studio® Add-In

Microsoft^® Visual C++ Express

To use Squish Coco with Microsoft^® Visual C++ Express proceed as follows:

1. Add the location of the CoverageScanner wrappers to the first position in the VC++ Directories.
   
   1. Start Microsoft^® Visual C++ Express.
   2. Open the option dialog: click on "Tools->Preferences…".
   3. Select the item "Projects->VC++ Directories".
   4. Add the entry $(SQUISHCOCO)\visualstudio to the first position in the list of directories. (see figure fig:visual_option_express_2005_fig)

      Installation of CoverageScanner on Visual C++ Express: Setting the path of CoverageScanner. Installation of CoverageScanner on Visual C++ Express: Setting the path of CoverageScanner.

2. The activation of the code coverage analysis is similar to Microsoft^® Visual Studio^® .NET. (see chap. visualstudiodotnet)

Microsoft^® Visual Studio^® 6.0

To use Squish Coco with Microsoft^® Visual Studio^® 6.0 proceed as follows:

1. Add the location of the CoverageScanner wrappers to the first position in the executable directories.
   
   1. Start Microsoft^® Visual Studio^® 6.0.
   2. Open the option dialog: click on "Tools->Preferences…".
   3. Select the item "Directories".
   4. Select "Executable files" in the combobox "Show directories for:".
   5. Add the path of the directory visualstudio of the Squish Coco installation² to the first position in the list of directories. (example: if Squish Coco is installed on c:\programme\SquishCoco, add the path c:\programme\SquishCoco\visualstudio, (see figure fig:visual_option_6_fig))

      Installation of CoverageScanner on Visual Studio® 6.0: Setting the path of CoverageScanner. Installation of CoverageScanner on Visual Studio® 6.0: Setting the path of CoverageScanner.

2. To activate the code coverage analysis:
   1. Open a Visual C or C++ project.
   2. Edit the project settings (click on "Project->Properties").
   3. Add the option --cs-on to the additional command line arguments of the C or C++ compiler and linker. (see figure fig:visual_compiler_6_fig)
   4. In the additional arguments of the linker, add the --cs-libgen which permits to specify which library should be used for the generation of the CoverageScanner library. The table tab:librarysettings contains the list of recommanded settings.

Activation of the instrumentation under Visual Studio® 6.0. Activation of the instrumentation under Visual Studio® 6.0.

Activation of the instrumentation under Visual Studio® 6.0. Activation of the instrumentation under Visual Studio® 6.0.

23.3.6  Microsoft^® eMbedded Visual C++^®

To use Squish Coco with Microsoft^® eMbedded Visual C++^®proceed as follows:

1. Add the location of the CoverageScanner wrappers to the first position in the executable directories.
   
   1. Start Microsoft^® eMbedded Visual C++^®.
   2. Open the option dialog: click on "Tools->Preferences…".
   3. Select the item "Directories".
   4. Select "Executable files" in the combobox "Show directories for:".
   5. Select "Platform" and the targeted "CPUs".
   6. Add the path of the directory WinCE of the Squish Coco installation³ to the first position in the list of directories. (example: if Squish Coco is installed on c:\programme\SquishCoco, add the path c:\programme\SquishCoco\WinCE, (see figure fig:visual_option_embedded_fig))

      Installation of CoverageScanner on eMbedded Visual C++®: Setting the path of CoverageScanner. Installation of CoverageScanner on eMbedded Visual C++®: Setting the path of CoverageScanner.

2. To activate the code coverage analysis:
   1. Open a Visual C or C++ project.
   2. Edit the project settings (click on "Project->Properties").
   3. Add the option --cs-on to the additional command line arguments of the C and C++ compiler and linker. (see figure fig:visual_compiler_embedded_fig)

Activation of the instrumentation under eMbedded Visual C++®. Activation of the instrumentation under eMbedded Visual C++®.

Activation of the instrumentation under eMbedded Visual C++®. Activation of the instrumentation under eMbedded Visual C++®.

23.3.7  Eclipse^™ IDE for C/C++

Eclipse^™ IDE for C/C++ rely on a GNU-GCC command line compiler. Before trying to compile a project with coverage support, it is necessary to create a compiler wrapper ((see chap. gcc-compiler)).


To compile a project with code coverage support, proceed as follows:

1. Start Eclipse^™.
2. Load a C or C++ project.
3. Open the property window (Project-> Properties)
4. Click on "C/C++ Build/Settings"
5. Create a new configuration by clicking on "Manage Configurations..." and select it.
6. Click on "Tools Settings" tab.
7. Click on "GCC C++ Compiler" and prepend cs to the name of the compiler.
8. Click on "GCC C Compiler" and prepend cs to the name of the compiler.
9. Click on "C++ Linker" and prepend cs to the name of the linker.

Eclipse™ settings Eclipse™ settings

23.3.8  Apple^® Xcode

To use Squish Coco with Apple^® Xcode proceed as follows: To activate the code coverage analysis:

1. Open a terminal window and set the CPLUSPLUS, LDPLUSPLUS, LD and CC to CoverageScanner compiler wrapper. Start Xcode using the open command. Example: 

   SQUISHCOCO=/Applications/SquishCoco/wrapper
   export CC=$SQUISHCOCO/gcc
   export LD=$SQUISHCOCO/gcc
   export CPLUSPLUS=$SQUISHCOCO/g++
   export LDPLUSPLUS=$SQUISHCOCO/g++
   
   open /Developer/Applications/Xcode.app
   

2. Open a Xcode C or C++ project.
3. Edit the project settings (click on "Project->Edit Project Settings").
4. Add the option --cs-on to the additional command line arguments of the C and C++ compiler (fields Other C Flags and Other C++ Flags) and linker (field Other Linker Flags). (see figure fig:xcode_configuration_fig)
5. Disable the usage of the precomiled header: Open the settings of the active target ("Project->Edit Active Target") and remove the contains of Prefix Header.

Activation of the instrumentation under Apple® Xcode. Activation of the instrumentation under Apple® Xcode.

Chapter 24  Command Line Reference

24.1  Synopsis

Where:

--cs-include-file-wildcard=<STRING>

This command line option enables the user to include a file in the coverage analysis. The file name is specified using a wildcard expression.
Example: --cs-include-file-wildcard=^c:\\include\\*.h includes all header file names with the extension .h located in c:\include.

--cs-exclude-file-wildcard=<STRING>

This command line option enables the user to exclude a file from the coverage analysis. The file name is specified using a wildcard expression.
Example: --cs-exclude-file-wildcard=*.h excludes all header file names with the extension .h.

--cs-exclude-file-abs-wildcard=<STRING>

Same as --cs-exclude-file-wildcard but on the absolute file path.

--cs-include-file-abs-wildcard=<STRING>

Same as --cs-include-file-wildcard but on the absolute file path.

--cs-include-file-regex=<STRING>

This command line option enables the user to include a file in the coverage analysis. The file name is specified using a regular expression. (see chapter sec:regular_expression for the syntax)
Example: --cs-include-file-regex=^c:\\include\\[^\\]*\.h$ includes all header file names with the extension .h located in c:\include.

--cs-exclude-file-regex=<STRING>

This command line option enables the user to exclude a file from the coverage analysis. The file name is specified using a regular expression. (see chapter sec:regular_expression for the syntax)
Example: --cs-exclude-file-regex=^.*\.h$ excludes all header file names with the extension .h.

--cs-exclude-file-abs-regex=<STRING>

Same as --cs-exclude-file-regex but on the absolute file path.

--cs-include-file-abs-regex=<STRING>

Same as --cs-include-file-regex but on the absolute file path.

--cs-exclude-path=<STRING>

This command line option enables the user to exclude the files located in a specific path from the code coverage analysis.
Example: --cs-exclude-path=c:\include excludes all files located in c:\include.

--cs-include-path=<STRING>

This command line option enables the user to include files located in a specific path in the coverage analysis.
Example: --cs-include-path=c:\include includes all files located in c:\include.

--cs-include-function-wildcard=<STRING>

This command line option enables the user to include a function in the coverage analysis. The function name is specified using a wildcard expression and must include for C++ code the class name and namespace.
Example: --cs-include-function-wildcard=C::* includes all members of the class C.

--cs-exclude-function-wildcard=<STRING>

This command line option enables the user to exclude a function from the coverage analysis. The function name is specified using a wildcard expression and must include for C++ code the class name and namespace.
Example: --cs-exclude-function-wildcard=*::Get* excludes all merbers of any classes which starts with Get.

--cs-include-function-regex=<STRING>

This command line option enables the user to include a function in the coverage analysis. The function name is specified using a regular expression and must include for C++ code the class name and namespace. (see chapter sec:regular_expression for the syntax)

--cs-exclude-function-regex=<STRING>

This command line option enables the user to exclude a function from the coverage analysis. The function name is specified using a regular expression and must include for C++ code the class name and namespace. (see chapter sec:regular_expression for the syntax)

--cs-compiler=<STRING>

This command option enables the user to select a profile. This option does not normally need to be specified, due to the fact that the profile name is usually extracted from the command line name. (cscl.exe implicitly selects the profile cl.cspro)
Example: --cs-compiler=cl selects the profile ’cl.cspro’.

--cs-architecture=<STRING>

Permits to specify the target architecture.

--cs-libgen=<STRING>

Adds an additional command line option to the compiler which generates the code coverage library. This command can be used more than once.

--cs-off

Disables the code coverage analysis of CoverageScanner. This is equivalent to calling the native compiler or linker.

--cs-on

Activates the code coverage analysis of CoverageScanner. This option is set by default.

--cs-hit

Generation of code coverage hit instrumentation. This option is set by default.

--cs-count

Generation of code coverage count instrumentation.

--cs-verbose

Verbose debug messages.

--cs-no-license-warning

Do not display a license warning when using CoverageScanner library.

--cs-branch

Generation of code coverage instrumentation of branches.

--cs-decision

Generation of code coverage instrumentation of branches and decisions.

--cs-condition

Generation of code coverage instrumentation of branches, decisions and conditions. (default)

--cs-partial-instrumentation

Suppression of redundant conditions.

--cs-full-instrumentation

No suppression of redundant conditions. (default)

--cs-no-exceptions

Do not instrument the catch block of a try…catch statement.

--cs-no-assignments

Do not instrument Boolean expressions in assignments.

--cs-boost

The code behind the macro BOOST_FOREACH is not instrumented. (this option is enabled per default)

--cs-no-boost

No specific handling for the Boost library.

--cs-qt4

Function filter which suppresses the instrumentation of class members (Q_OBJECT, qt_metacall, qt_metacast, …) generated by Nokia moc for Qt4 library. The code behind the macro Q_FOREACH is also not instrumented. (this option is enabled per default)

--cs-no-qt4

No specific handling for the Qt4 library.

--cs-qt3

Function filter which suppresses the instrumentation of class members (Q_OBJECT, className, tr, …) generated by Nokia moc for Qt3 library. (this option is enabled per default)

--cs-no-qt3

No specific handling for the Qt3 library.

--cs-output=<STRING>

Set the default output file name of the execution report. Per default, CoverageScanner uses the application name (without the path). The extension .csexe is added automatically.

--cs-output-abs

Set the default output file name of the execution report to the absolute file name of the generated application. The extension .csexe is added automatically.

The file name is calculated during the code generation, moving the application to an other directory does not update this report file name.

Using simultaneously --cs-output and --cs-output-abs command line arguments is not allowed.

--cs-lock-csexe

Create a lock file which lock the access of the .csexe file during its generation.

--cs-nolock-csexe

Inverse option to --cs-lock-csexe.

--cs-pipe

The preprocessor output is transmitted to CoverageScannerthrough a pipe. This option is set by default.

--cs-nopipe

The preprocessor output is transmitted to CoverageScannerthrough a temporary file.

--cs-keep-instrumentation-files

Do not delete temporary source files.

--cs-library-after=<STRING>

Add CoverageScanner library after the linker command line argument <STRING>.

24.2  Instrumenting using preprocessor defines

CoverageScanner activates also the instrumentation if some defines are present in the command line option. This permits to instrument code with an IDE which does not permits to add custom command line options to the compiler or linker.
Example: Defining COVERAGESCANNER_COVERAGE_ON is equivalent of adding --cs-on to the command line.

24.3  C and C++ Library

CoverageScanner library is generated during the link process and enables the user to:

1. Initialize measurements.
2. Generate the execution report.
3. Give a name to the executed tests.
4. Install a signal handler which saved the execution report on exit.

Additionally CoverageScanner sets the preprocessor define __COVERAGESCANNER__ which excludes this function from a normal compilation.

24.3.1  __coveragescanner_install

Syntax: void __coveragescanner_install(const char *appname)


__coveragescanner_install performs complete initialization of the CoverageScanner library. This function is the first function called in the main() function. The parameter appname contains the executable name. The application name is used to define the measurement file name (by appending ’.csexe’ to appname).


__coveragescanner_install registers an exit handler via atexit() which stores execution traces using the __coveragescanner_save procedure. This handler is also called when SIGABRT, SIGTERM, SIGFPE, SIGILL, SIGINT, SIGSEGV and SIGTERM signal are received. This makes it possible to save the execution report upon every application termination.


Suggested usage:

24.3.2  __coveragescanner_testname

Syntax: void __coveragescanner_testname(const char *name)


__coveragescanner_testname sets the name of the test which is currently being executed. It will be saved to the execution report and is displayed in the "Executions" window (see chap. execution-management) when the loaded in CoverageBrowser.

24.3.3  __coveragescanner_teststate

Syntax: void __coveragescanner_teststate(const char *state)


__coveragescanner_teststate sets the state of the test which is currently being executed. The string parameter state can have the following values:

"PASSED"

indicates that the test was successfully executed.

"FAILED"

indicates that the test was not successfully passed.

"CHECK_MANUALLY"

indicates that it was not possible to determinate if the test was successfully executed.

It will be saved to the execution report and is displayed in the "Executions" window (see chap. execution-management) when the loaded in CoverageBrowser.

24.3.4  __coveragescanner_add_html_comment

Syntax: void __coveragescanner_add_html_comment(const char *comment)


__coveragescanner_add_html_comment append a comment to the current execution. The comments needs to follow the HTML syntax but only the body is parsed. (The contains of the “<HEAD>” tag is ignored). This function can be called several times, in this case the contains is appended.

24.3.5  __coveragescanner_clear_html_comment

Syntax: void __coveragescanner_clear_html_comment()


__coveragescanner_clear_html_comment clear comments added using void __coveragescanner_add_html_comment(const char *comment).

24.3.6  __coveragescanner_save

Syntax: void __coveragescanner_save()


__coveragescanner_save saves the execution report and resets the status of all instrumentations.

24.3.7  __coveragescanner_clear

Syntax: void __coveragescanner_clear()


__coveragescanner_clear resets the status of all instrumentations.

24.3.8  __coveragescanner_filename

Syntax: void __coveragescanner_filename(const char *name)


this function sets the file name of the execution report. The extension ’.csexe’ is added automatically. The name must be less than 80 characters.

24.3.9  __coveragescanner_register_library

Syntax: int __coveragescanner_register_library(const char *library_name)


__coveragescanner_register_library register a shared library loaded on demand. Once registered the code coverage of the library is saved transparently when calling __coveragescanner_save from the main application.


Returned values:

0

Success.

-1

Error: library cannot be loaded.

-2

Error: invalid library name.

1

Success, but library was already registered. Use count is incremented.

2

Success, but library is not instrumented.

24.3.10  __coveragescanner_unregister_library

Syntax: int __coveragescanner_unregister_library(const char *library_name)


__coveragescanner_unregister_library cancel a register of a shared library loaded on demand.


Returned values:

0

Success.

-1

Error: library not registered.

-2

Error: invalid library name.

1

Success, but library is not unregistered because the use count is not null.

2

Success, but library is not instrumented.

24.3.11  __coveragescanner_set_custom_io

Syntax: void __coveragescanner_set_custom_io(
           char *(*csfgets)(char *s, int size, void *stream),
           int (*csfputs)(const char *s, void *stream),
           void *(*csfopenappend)(const char *path),
           void *(*csfopenread)(const char *path),
           void *(*csfopenwrite)(const char *path),
           int (*csfclose)(void *fp), 
           int (*csremove)(const char *filename) ) 



Parameters:

csfgets

csfgets reads in at most one less than size characters from stream and stores them into the buffer pointed to by s. Reading stops after an EOF or a newline. If a newline is read, it is stored into the buffer. A ’\0’ is stored after the last character in the buffer.

csfputs

csfputs writes the string s to stream, without its trailing ’\0’.

csfopenappend

csfopenappend open the file path for writing at the end.

csfopenread

csfopenread open the file path for reading.

csfopenwrite

csfopenwrite open the file path for writing.

csfclose

The csfclose function will flush and close the stream pointed to by fp.

csremove

csremove removes filename from the file system.

CoverageScanner writes the execution report (.csexe file) into file using the common C library (fopen, fputs, …). In some situations, for embedded systems for example, it is necessary to use an other way for recording it. For this reason, CoverageScanner provides __coveragescanner_set_custom_io which permits to replace the IO functions used by __coveragescanner_save.

Default implementation:

Some examples are available in the annex customioexample.

24.4  Controlling the instrumentation during the compilation

CoverageScanner offers the possibility to modify the coverage settings of some source code parts during the compilation. This permits, for example, to exclude some source code from the coverage analysis.

24.4.1  C and C++ Pragma

CoverageScanner defines C and C++ pragmas which permits to control during the compilation the generation of the instrumentation. All control commands are handled in a stack. The pragmas have the following syntax:
#pragma CoverageScanner ( string )
or: __pragma ( CoverageScanner ( string ) )
or: _Pragma ( CoverageScanner ( string ) )

List of supported pragmas:

#pragma CoverageScanner(cov-on)

Enables code coverage instrumentation.

#pragma CoverageScanner(cov-off)

Disables code coverage instrumentation.

#pragma CoverageScanner(cov-hit)

Instruments using code coverage hit.

#pragma CoverageScanner(cov-count)

Instruments using code coverage count.

#pragma CoverageScanner(cov-branch)

Select the code coverage branch as instrumentation method.

#pragma CoverageScanner(cov-decision)

Select the code coverage decision as instrumentation method.

#pragma CoverageScanner(cov-condition)

Select the code coverage condition as instrumentation method.

#pragma CoverageScanner(cov-partial-instrumentation)

Partial instrumentation of conditions and decisions.

#pragma CoverageScanner(cov-full-instrumentation)

Full instrumentation of conditions and decisions.

#pragma CoverageScanner(cov-assignment-on)

Instrument Boolean expressions in assignments.

#pragma CoverageScanner(cov-assignment-off)

Stop instrumenting Boolean expressions in assignments.

#pragma CoverageScanner(pop)

Restore the instrumentation option before the call of the last CoverageScanner pragma.

24.5  Regular Expressions

Regular expressions are composed of items (see table tab:regexp_item for the full list) and combining operators. These can be:

• […]: The brackets are used to define a set of characters. For example, [123] corresponds to the characters 1, 2 or 3. It is possible to define a range using the minus sign: [a-z] corresponds to all characters between a and z.
• [^…]: The caret defines a set of characters which should not match. For example, [^0-9] corresponds to any character except a digit.
• ?: The question mark after a regular expression item makes it optional.
  Example: ab? matches the string a or ab.
• +: The plus operator makes it possible to repeat the regular expression item.
  Example: ab+ matches every strings ab…b.
• *: The star operator after a regular expression item signifies that the item is optional and can be repeated.
  Example: ab* matches every string ab…b and a.
• |: The pipe operator specifies an alternative.
  Example: a|b matches the character a or b.
• (…): The parenthesis groups expressions into sub-expressions.
  Example: (true)|(false) matches the string true or false.
• Regular Expression Items: The regular expression items are ASCII or magic characters (See table tab:regexp_item for the complete list). If a magic character needs to be used as an ASCII character, it has to be escaped with a backslash (\).

Chapter 25  Code Coverage of Libraries

25.1  Code Coverage of Static/Shared Libraries and DLL

During the linking operation, CoverageScanner includes all instrumentations of the shared libraries (if these are compiled with CoverageScanner). CoverageBrowser displays the code coverage of the complete application (executable and its libraries) in one view.

25.2  Code Coverage of Plugins/Manually Loaded Shared Libraries

CoverageScanner cannot handle the instrumentation of plugins (i.e. shared libraries loaded manually) during the linking phase. In this case, the library must initialize and store itself the executions.
Therefore, the shared library needs to call __coveragescanner_filename to set the name of the execution file during its initialization and __coveragescanner_save to save the instrumentations when its becomes unloaded.

25.2.1  Code Coverage of Plugins Generated with Microsoft^® Visual Studio^®

The function DllMain is called on the initialization and the termination of the DLL generated using Microsoft^® Visual Studio^®. When the ’reason’ field is equal to DLL_PROCESS_ATTACH the function __coveragescanner_filename should be called. To save the measures on exit the function __coveragescanner_save shall be called when ’reason’ is DLL_PROCESS_DETACH.

Example:

25.2.2  Code Coverage of Plugins Generated with GNU gcc

The GNU compiler offers 2 attributes which permits to execute a function when a library becomes loaded or unloaded:

__attribute__ ((constructor)) my_init(void);

This attribute permits to call a function when the library is loaded. Call the function __coveragescanner_filename in the custom initialization function of the library.

__attribute__ ((destructor)) my_fini(void);

This attribute permits to call a function when the library is unloaded. Call the function __coveragescanner_save on the termination of the library.

Example:

Chapter 26  Test Suite and Squish Coco

26.1  Execution Comment, Name And Status

Test suites are able to provide to CoverageBrowser the name of the test, a comment in HTML format and also the status of their execution (passed or failed). Two methods are possible:

• Using the functions __coveragescanner_testname, __coveragescanner_add_html_comment and __coveragescanner_teststate can be used to specify the test name, its comment and its status. This is particularly useful for unit tests in which the test framework is compiled into the application to test.(see chap. executionreportname)
• Writing directly into the .csexe file this information. (see below)

The .csexe file is a simple text file on which is it possible to append additional lines to extend the information provided to CoverageBrowser.

To set the name of a test simply add before executing it the following line: §name of the test\n
or
*name of the test\n
The character * or § must be the first character of the line. The name of the test is placed directly after and a is terminated with a carriage return.

To set the status of a test simply add after executing it the following line: !status\n
The character ! must be the first character of the line. The status of the test is placed directly after and a is terminated with a carriage return. The status can be one of the following strings:

"PASSED"

indicates that the test was successfully executed.

"FAILED"

indicates that the test was not successfully passed.

"CHECK_MANUALLY"

indicates that it was not possible to determinate if the test was successfully executed.

To append an execution comment, insert the contains of a HTML document just after the execution of the application.

Example: the following batch file execute the test First Test and set the status of the execution to CHECK_MANUALLY.

echo *First Test >> myapp.csexe
myapp
echo "<HTML><BODY>Execution of myapp</BODY><HEAD>" >> myapp.exe
echo !CHECK_MANUALLY >> myapp.csexe

26.2  Unit Testing

CoverageBrowser import execution results for each object which are part of an application. This mean that, if an unit test uses the same objects as these for generating the application, CoverageBrowser is able to import the execution result of the unit test and merge it into the code coverage of the compiled application.

Example: 
An application is composed to 3 files:

app.cpp

This file contains the main() function of the application.

library.cpp

This file contains a set of functions called in app.cpp.

testlibrary.cpp

This contains the test code of the functions of the file library.cpp. testlibrary.cpp have its own main() function.

To generate the application:

cscl app.cpp /Foapp.obj
cscl library.cpp /Folibrary.obj
cscl library.obj app.obj /Feapp.exe

To generate the unit test:

cscl testlibrary.cpp /Fotestlibrary.obj
cscl library.obj testlibrary.obj /Fetestlibrary.exe

To import the execution report from the unit tests into the instrumentation database of the main application, two methods can be used:

• The execution of testlibrary.exe generates the execution report testlibrary.exe.csexe. This report can be loaded in the measurement database app.exe.csmes.
• The execution of testlibrary.exe generates the execution report testlibrary.exe.csexe. This report can be loaded in the measurement database testlibrary.exe.csmes of the test code. This measurement database can be imported into this one from the main application using "File->Import Unit Tests…" function of CoverageBrowser. (see chap. import-unit-test)

In both cases, only the code coverage analysis of the file library.cpp is loaded, and the execution report of the test code is ignored.

26.3  Test Framework Support

26.3.1  CppUnit

CppUnit¹ is a unit test framework for C++. This environment can easily be adapted to get the code coverage from each unit test.
Simply proceed as follows:

1. Call __coveragebrowser_install() in the main() function.
2. Write a CppUnit TestListener class which records the code coverage report upon every unit test completion. The listener should set the name (using __coveragescanner_testname()) and clear the instrumentation (using __coveragescanner_clear()) before executing a test item (class member startTest()) to ensure to get only the coverage data of the concerned test. When an test item is executed, the instrumentation and the execution status should be saved (using __coveragescanner_teststate() and __coveragescanner_save()) in the class member endTest(). The class CoverageScannerListener give an implementation example.
3. Add this listener in the test manager of CppUnit (class CPPUNIT_NS::TestResult).
   In the example below

   CoverageScannerListener coveragescannerlistener;
   controller.addListener( &coveragescannerlistener );        
   

4. Compile the unit test using CoverageScanner.

To download: http://froglogic.com/squish/coco//CppUnitListener.cpp

26.3.2  QTestLib

QTestLib² is a unit test framework for the Qt Library. This environment can easily be adapted to get the code coverage from each unit test.
Simply proceed as follows:

1. Call __coveragebrowser_install() in the main() function.
2. Write a QObject derived class called TestCoverageObject which records the code coverage report upon every unit test completion.
3. Instead of inheriting from QObject, make all your test cases inheriting from TestCoverageObject.
4. TestCoverageObject class provide its own init() and cleanup() slot, which use the CoverageScanner API to save the code coverage report. If these slots are also declared in the test case class, it is necessary to rename it in initTest() and cleanupTest().
5. Compile your project with code code coverage enabled.

TestCoverageObject header:

To download: http://froglogic.com/squish/coco//testcoverageobject.h

TestCoverageObject source:

To download: http://froglogic.com/squish/coco//testcoverageobject.cpp

26.3.3  GoogleTest

GoogleTest³ is a unit test framework for C++. This environment can easily be adapted to get the code coverage from each unit test.
Simply proceed as follows:

1. Call __coveragebrowser_install() in the main() function.
2. Write a TestEventListenet class which records the code coverage report upon every unit test completion. The listener should set the name (using __coveragescanner_testname()) and clear the instrumentation (using __coveragescanner_clear()) before executing a test item (class member startTest()) to ensure to get only the coverage data of the concerned test. When an test item is executed, the instrumentation and the execution status should be saved (using __coveragescanner_teststate() and __coveragescanner_save()) in the class member endTest(). The class CodeCoverageListener give an implementation example.
3. Add this listener in the Append function of the GoogleTest listener (function ::testing::UnitTest::GetInstance()->listeners().Append()).
4. Compile the unit test using CoverageScanner.

To download: http://froglogic.com/squish/coco//googletest.cpp

26.3.4  CxxTest

CxxTest⁴ is a unit test framework for C++. This environment can easily be adapted to get the code coverage from each unit test.
Simply proceed as follows:

1. Call __coveragebrowser_install() in the main() function.
2. Create a CxxTest TestListener class called CoverageScannerListener by subclassing an existing listener (in the example bellow: ErrorPrinter). It will record the code coverage report upon every unit test completion. The listener should set the name (using __coveragescanner_testname()) and clear the instrumentation (using __coveragescanner_clear()) before executing a test item (class member enterTest()) to ensure to get only the coverage data of the concerned test. When an test item is executed, the instrumentation and the execution status should be saved (using __coveragescanner_teststate() and __coveragescanner_save()) in the class member leaveTest(). Finally, all test failure members of this class need to be reimplemented to record the test failure.
3. In the main() function call the run() function of CoverageScannerListener instead of CxxTest::ErrorPrinter().run().
4. Compile the unit test using CoverageScanner.

To download: http://froglogic.com/squish/coco//CxxTestListener.cpp

Add CoverageScanner library at the end of the command line.

1

Project page of CppUnit:http://cppunit.sourceforge.net

2

Unit test framework from Nokia:http://doc.trolltech.com/qt/qtestlib_manual.html

3

Project page of GoogleTest:http://code.google.com/p/googletest/

4

Project page of CxxTest:http://cxxtest.sourceforge.net