Coco integration handbook Support for specific test frameworks

Support for IDEs and toolchains

In this chapter we give examples how Coco can be combined with several IDEs and build environments.

GNU makefiles

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

For example: make LINK=csg++ CXX=csg++ CC=csgcc

CygWin

To install the CoverageScanner compiler wrapper for GCC and G++ on CygWin:

  1. Open the Build Environment Selection application (<Windows Coco>\toolselector.exe).
  2. Select the item CygWin - www.cygwin.com.
  3. Click Install CygWin Support. The build environment selection dialog then displays the list of generated compiler wrappers.

Open then the CygWin console and compile your application with csgcc instead of gcc (or csg++ instead of g++).

Scratchbox

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

Note: Installation option: 1) Installation on the local machine (need to be root).

CMake

CMake is a platform independent build tool from Kitware.

When Coco is used with CMake, the changes are partially dependent on the toolchain that is used for compilation. We will now first describe the addition of a new build type, which is independent from the toolchain, and then the additional changes for Microsoft® Visual Studio® and GNU GCC.

Adding new build type for instrumented compilation

The first step is independent of the toolchain that is used. Its purpose is to declare the CMake variables that are used to specify the instrumented compilation. In CMake this is done by declaring a build type, which we will here call COVERAGE.

To do this, add to the to CMakeLists.txt file the following lines. The variable COVERAGE_FLAGS in the first line specifies the CoverageScanner command line options. Change its value to fit your needs. Only --cs-on must always be present.

SET(COVERAGE_FLAGS "--cs-on --cs-count")
SET(CMAKE_CXX_FLAGS_COVERAGE
    "${CMAKE_CXX_FLAGS_RELEASE} ${COVERAGE_FLAGS}" CACHE STRING
    "Flags used by the C++ compiler during coverage builds."
    FORCE )
SET(CMAKE_C_FLAGS_COVERAGE
    "${CMAKE_C_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
)

These commands take the compiler and linker flags of the Release build type and add to them the coverage flags. If you want to use instead the flags of another build type, replace the suffix _RELEASE in this code with the name of another build type, such as _DEBUG.

Microsoft Visual Studio

In Visual Studio, we need to make the new Coverage build type visible to the IDE. To do this, add to CMakeLists.txt the lines:

if(CMAKE_CONFIGURATION_TYPES)
   set(CMAKE_CONFIGURATION_TYPES Debug Release MinSizeRel RelWithDebInfo Coverage)
   set(CMAKE_CONFIGURATION_TYPES "${CMAKE_CONFIGURATION_TYPES}" CACHE STRING
     "Reset the configurations to what we need" FORCE)
endif()

If necessary, customize the list of configuration types according to your needs. To make the changes visible to Microsoft Visual Studio, a complex procedure is apparently needed. This applies at least to CMake 3.2 and Microsoft Visual Studio 2013:

  1. Compile CMakeLists.txt with Ctrl-F7. If warnings occur, they can be ignored.
  2. Make a trivial change in CMakeLists.txt, like adding a space.
  3. Compile again to open the File modification detected dialog, and click Reload.

The list of solution configurations is updated and you can compile in coverage mode.

Compilation with Microsoft NMake

In a project that is compiled with NMake:

  1. Create a toolchain definition file cl.cmake which replaces the compiler and linker with their CoverageScanner wrappers.

    For 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. Set the toolchain to the CoverageScanner wrapper and the build mode to COVERAGE.

    For example:

    cmake.exe -DCMAKE_TOOLCHAIN_FILE=cl.cmake -DCMAKE_BUILD_TYPE=COVERAGE \
          -G "NMake Makefiles" <i>path of cmake project</i>
  3. Build the project with nmake.

Compilation with GNU GCC

The following must be done in a project that is compiled with gcc:

  1. Create a toolchain definition file gcc.cmake which replaces the compiler and linker with their CoverageScanner wrappers.

    For example:

    find_program(CODE_COVERAGE_GCC gcc
    PATHS /opt/SquishCoco/wrapper/bin "$ENV{HOME}/SquishCoco/wrapper/bin"
    NO_DEFAULT_PATH )
find_program(CODE_COVERAGE_GXX g++
    PATHS /opt/SquishCoco/wrapper/bin "$ENV{HOME}/SquishCoco/wrapper/bin"
    NO_DEFAULT_PATH )
find_program(CODE_COVERAGE_AR ar
    PATHS /opt/SquishCoco/wrapper/bin "$ENV{HOME}/SquishCoco/wrapper/bin"
    NO_DEFAULT_PATH )

# 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. Set the toolchain to the CoverageScanner wrapper and the build mode to COVERAGE.

    For example:

    cmake -DCMAKE_TOOLCHAIN_FILE=gcc.cmake -DCMAKE_BUILD_TYPE=COVERAGE \
      -G "Unix Makefiles" <i>path of cmake project</i>
  3. Build the project with make.

Qt framework

qmake

qmake is a tool that is used by Qt to generate a makefile in a platform-independent way, using as specification a so-called project file. It is also used by Qt Creator.

By default, qmake chooses the programs that are used for compilation. We can use the Coco wrappers by setting some of qmake's variables to new values. This can be done by putting some declarations into the qmake project files. Since one needs to build the project with and without coverage, the new definitions must be put into a scope. A scope is a region in a qmake project file that can be activated on demand.

The following listing shows a template for such a scope, named CoverageScanner, which should be sufficient for most projects.

CodeCoverage {
  COVERAGE_OPTIONS =

  QMAKE_CFLAGS   += $$COVERAGE_OPTIONS
  QMAKE_CXXFLAGS += $$COVERAGE_OPTIONS
  QMAKE_LFLAGS   += $$COVERAGE_OPTIONS

  QMAKE_CC=cs$$QMAKE_CC
  QMAKE_CXX=cs$$QMAKE_CXX
  QMAKE_LINK=cs$$QMAKE_LINK
  QMAKE_LINK_SHLIB=cs$$QMAKE_LINK_SHLIB
  QMAKE_AR=cs$$QMAKE_AR
  QMAKE_LIB=cs$$QMAKE_LIB
}

Here we also set the variables QMAKE_LINK_SHLIB and QMAKE_AR, which contain the names of the command to link shared libraries and that to generate archives. Furthermore, you can use COVERAGE_OPTIONS to set coveragescanner command line options (see List of options) to customize the project. An empty value for COVERAGE_OPTIONS will also work and results in a default instrumentation.

In a small project, the CodeCoverage scope may then be copied to all profile files of the project, i.e. those that end in .pro. In fact, it is enough to insert them only into those files that actually compile code and not those that only include other files. If the project is larger, it has very often a file with common settings that is included by all profiles: This is then the most convenient place to insert the CodeCoverage scope only once.

The new coverage scope is by default inactive. To enable code coverage in a project you want to built, just add the name of the scope to the CONFIG variable when configuring it with qmake:

$ qmake CONFIG+=CodeCoverage

moc

The Meta-Object Compiler (moc) generates some methods for each class derived from QObject. 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 Framework and not moc-generated code, CoverageScanner provides the command line options --cs-qt3 for Qt3 and --cs-qt4 for Qt4 to Qt6. They are enabled by default.

In this case:

  • Q_OBJECT macro is no longer instrumented.
  • All signals 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 in Qt4.

qbs

To use CoverageScanner with the Qt Build Suite (qbs), set it up as a toolchain. You can then use the toolchain for all qbs projects.

To set up CoverageScanner as a toolchain, issue the following command:

qbs setup-toolchains --type gcc /opt/SquishCoco/bin/csgcc csgcc

For Unix-based operating systems, some additional configuration steps are necessary:

qbs config profiles.csgcc.cpp.archiverPath /opt/SquishCoco/bin/csar
qbs config profiles.csgcc.cpp.linkerName csg++
qbs config profiles.csgcc.cpp.nmPath /opt/SquishCoco/bin/csgcc-nm

The csgcc toolchain can then also be used as base profile for Qt projects:

qbs setup-qt /opt/Qt/bin/qmake qt-csgcc
qbs config profiles.qt-csgcc.baseProfile csgcc

SCons

To use Coco with SCons:

  1. Prepend the path of CoverageScanner's wrapper (csgcc, cscl, and son on) to the PATH environment variable. The PATH environment variable should be set to be able to execute CoverageScanner wrappers.
  2. Set CC, AR and LINK variables to the corresponding CoverageScanner wrapper. For example: when using Microsoft Visual Studio compiler, set CC to cscl.exe, LINK to cslink.exe, and AR to cslib.exe.

    Note: Do no use absolute file paths to the compiler wrapper since some versions of SCons do not properly handle spaces in file names.

  3. Add code coverage settings to exclude from the instrumentation for example files to the variables CCFLAGS, ARFLAGS and LINKFLAGS.

Here is a code snippet which can be used for Visual Studio command line tools:

import os
from os.path import pathsep

env = Environment()

# Add the path of Squish Coco compiler wrapper
env[ 'ENV' ][ 'PATH' ] = os.environ[ 'SQUISHCOCO' ] + pathsep + env[ 'ENV' ][ 'PATH' ]
# TEMP variable need to be defined
env[ 'ENV' ][ 'TEMP' ] = os.environ[ 'TEMP' ]
env[ 'ENV' ][ 'INCLUDE' ] = os.environ[ 'INCLUDE' ]

# Set the compiler to Squish Coco wrappers
env[ 'CC' ]   = 'cs' + env[ 'CC' ] ;
env[ 'AR' ]   = 'cs' + env[ 'AR' ] ;
env[ 'LINK' ] = 'cs' + env[ 'LINK' ] ;

# Code coverage settings
coverageflags = [ '--cs-count' ]
env[ 'CCFLAGS' ]   = env[ 'CCFLAGS' ] + coverageflags ;
env[ 'ARFLAGS' ]   = env[ 'ARFLAGS' ] + coverageflags ;
env[ 'LINKFLAGS' ] = env[ 'LINKFLAGS' ] + coverageflags ;

To correctly set the build environment, you must start the build from the Visual Studio's developer prompt (available through the start menu) or the Coco's console provided by Build Environment Selection.

TI C6000 CGT6

There is no standard location to install this compiler. However, TI compiler Coco wrappers are installed in %squishcoco%\TI.

To instrument programs that are built with the TI cl6x compiler, you must either

  • Add the Coco compiler wrappers to your PATH (before the actual compiler), or
  • run the Build Environment Selection, which, when given an install location of the TI compiler, will move the original executables to a different directory and place wrappers in the original location.

With the second approach, the wrappers will simply pass on the command line arguments to the underlying compilers unless --cs-on is passed as a command line argument or found in the COVERAGESCANNER_ARGS environment variable, in which case, Coco instrumentation happens.

To install CoverageScanner compiler wrapper for the TI C6000 cl6x toolchain:

  1. Open the Build Environment Selection application (%squishcoco%\toolselector.exe).
  2. Select the item TI CGT 6.
  3. Select the directory to which the TI CGT 6 compiler is installed installed (for example, C:\Desktop\TI).
  4. Click Install TI Support and wait for the confirmation that the tools are generated.

Synopsys Metaware Designware ARC

There is no support for Metaware compilers yet in the Build Environment Selection, so don't bother looking for Metaware there. However, Squish Coco provides wrappers for 2 Metaware compilers: ccac and arac.

After the Metaware compiler is installed on Windows, an environment variable, METAWARE_ROOT is defined, and the compiler is installed below that directory. The installer adds these directories to your PATH: %METAWARE_ROOT%\arc\bin;%METAWARE_ROOT%\ide.

For it to be possible to instrument your builds, add the directory of the Coco Metaware wrappers to the start of your PATH. If you are using the command shell, it looks like this:

set PATH=%squishcoco%\Metaware;%PATH%

To instrument programs with one of our compiler wrappers, add --cs-on and whatever other coveragescanner arguments you like to the COVERAGESCANNER_ARGS environment variable.

set COVERAGESCANNER_ARGS=--cs-on --cs-mcdc

After that, you can run gmake from the command line to build your application, and you should get an instrumented build.

Alternately, from the Metaware IDE, you can set these environment variables from Project - Properties - C/C++ Build - Environment.

To setup code coverage for a project, go to Manage Configurations - New and create a new configuration called CodeCoverage. Select it, and set it to Active.

Next, set the PATH and the COVERAGESCANNER_ARGS in the Environment section.

After this, the IDE should be able to build instrumented executables of your project.

If you no longer want code coverage, switch back to one of the previous build configurations.

ARM Keil μVision

To enable the code coverage analysis, compile the project with Coco compiler wrapper for ARM and enable the code coverage analysis during the compilation:

  1. To install CoverageScanner compiler wrapper for the ARM® Keil® μVision toolchain:
    1. Open the Build Environment Selection application (<Windows Coco>\toolselector.exe).
    2. Select the item ARM-Keil.
    3. Select the directory to which the ARM Keil μVision compilers are installed (for example, C:\Keil_v5\ARM).
    4. Click Install ARM-Keil Support and wait for the confirmation that the tools are generated.
  2. Activate the code coverage analysis during the compilation:
    1. Click Project > Option for Target.
    2. On the C/C++ tab, add --cs-on into the Misc Controls field.

    3. On the Linker tab, add --cs-on into the Misc Controls field.

Arm DS

To enable the code coverage analysis for an Arm DS project, compile it with Coco compiler wrapper for ARM and enable the code coverage analysis during the compilation:

  1. To install CoverageScanner compiler wrapper for the Arm DS toolchain:
    1. Open the Build Environment Selection application (<Windows Coco>\toolselector.exe).
    2. Select the item ARM-DS.

      "Installation of Arm DS support in Build Environment Selection"

    3. Select the directory o which the Arm DS compilers are installed (for example, C:\Program Files\DS-5 v5.29.3)
    4. Click Install ARM-DS Support and wait for the confirmation that the tools are generated.

      "Confirmation of the installation of Arm DS support"

  2. Activate the code coverage analysis during the compilation:
    1. Click Project > Properties.
    2. On the Arm C/C++ Compiler 5 tab, add --cs-on into the Miscellaneous field.

      "Activating the code coverage analysis for an Arm compiler"

    3. On the Arm Linker 5 tab, add --cs-on into the Misc Controls field.

      "Activating the code coverage analysis for an Arm linker"

To upload the coverage data from the target to the host, define some custom I/O functions and trigger the coverage generation by calling __coveragescanner_save(). Due to the fact that Arm DS supports semi-hostings extensions, the simplest way is to use it to generate the execution report directly on the host file system.

For that modify the main() function to add a call to __coveragescanner_set_custom_io(), __coveragescanner_filename() and __coveragescanner_save() as in the following sample:

*
    #include <stdio.h>

    #ifdef __COVERAGESCANNER__
    static int csfputs(const char *s, void *stream)
    {
      return fputs(s, (FILE *)stream);
    }

    static void *csfopenappend(const char *path)
    {
      return (void*)fopen(path,"a+");
    }

    static int csfclose(void *fp)
    {
      return fclose((FILE*)fp);
    }
    #endif

    int main() {
    #ifdef __COVERAGESCANNER__
      __coveragescanner_set_custom_io( NULL,
          csfputs,
          csfopenappend,
          NULL,
          NULL,
          csfclose,
          NULL);
      __coveragescanner_filename( "c:\\tmp\\test_arm5_csexe" ); /* destination file on the host file system */
    #endif
      .......
    #ifdef __COVERAGESCANNER__
        __coveragescanner_save(); /* saves the execution report */
    #endif
        return 0;
    }

The project can now be rebuilt and a project file with the extension .afx.csmes will be generated. This file can be opened in CoverageBrowser. Execute then the target application and wait until __coveragescanner_save() is called. A file c:\tmp\test_arm5_csexe will be generated (hard coded in our sample). Import and analyze it using CoverageBrowser as in the following screenshot:

Code coverage of an Arm DS project

Note: The extension of an execution report is usually .csexe but the semi-hosting implementation provided by ARM removes the file extensions. It is necessary to remove the default file filter in the import dialog of CoverageBrowser to be able to import it.

Green Hills Software MULTI Launcher

Installation

To install CoverageScanner compiler wrapper for the Green Hills® Software toolchain:

  1. Open the Build Environment Selection application (<Windows Coco>\toolselector.exe).
  2. Select the item Green Hills.
  3. Select the directory to which the Green Hills Software compilers are installed.
  4. Click Install Green Hills Support and wait for the confirmation dialog the tools are generated.

Command line tools

The command line tools for the Green Hills Software compiler are installed in the folder squishcoco of the installed native toolchain. For example, if the native toolchain is installed under c:\ghs\comp_201426, the Coco compiler wrappers are installed under c:\ghs\comp_201426\squishcoco.

The compiler wrappers completely replace the Green Hills Software toolchain. To activate the code coverage analysis, add the parameter --cs-on to the compiler arguments.

CoverageScanner library

To save an execution report:

  1. Provide to the CoverageScanner library a list of I/O functions which let you upload the coverage information to the host.
  2. Save manually the coverage report on a specific trigger.

To save a coverage report, use the following code snippet (add this code in an event handler which should trigger the report generation):

#ifdef __COVERAGESCANNER__
    __coveragescanner_save();
    __coveragescanner_clear();
#endif

To provide the I/O functions, call __coveragescanner_set_custom_io() in the main() function of the application. At least three functions need to be provided by __coveragescanner_set_custom_io():

  1. An equivalent function of fopen() which opens the execution report file (with the extension .csexe) in append mode.
  2. An equivalent function of fclose().
  3. An equivalent function of fputs() to transfer the contents.

For example, the following code writes an execution report to the local file system using the C file API.

#ifdef __COVERAGESCANNER__
static int csfputs(const char *s, void *stream) { return fputs(s, (FILE *)stream); }
static void *csfopenappend(const char *path)    { return (void*)fopen(path,"a+");  }
static int csfclose(void *fp)                   { return fclose((FILE*)fp);        }
#endif

int main()
{
#ifdef __COVERAGESCANNER__
    __coveragescanner_set_custom_io( NULL,
            csfputs,
            csfopenappend,
            NULL,
            NULL,
            csfclose,
            NULL);
#endif
....
}

QNX Software Momentics IDE

Installation

To install CoverageScanner compiler wrapper for the QNX® Software toolchain:

  1. Open the Build Environment Selection application (<Windows Coco>\toolselector.exe).
  2. Select the item QNX.
  3. Select the directory on which the QNX Software toolchain is installed. By default, it is c:\Users\<account>\qnx700.
  4. Click Install QNX Support and wait for the confirmation that the tools are generated.

Configuration

Once the installation process is done, activate and configure the Coco parameters for a selected build mode. Or create a dedicated mode just for the code coverage, which is a better practice.

QNX Software 7.0

Proceed as follows:

  1. Open QNX Momentics IDE.
  2. Load the project to instrument.
  3. Open the project's preferences with the menu Project > Properties.

    "Project settings on Momentics IDE 7.0"

  4. Select C++ Build > Environment and add the variable COVERAGESCANNER_ARGS with the value --cs-on. You can specify additional settings. For example, to enable the MC/DC instrumentation, add --cs-mcdc.
  5. Rebuild your project to find in your build folder the instrumentation database <project_name>.csmes. You can then execute your application and import the generated .csexe file into it.

QNX Software 7.1

Proceed as follows:

  1. Open QNX Momentics IDE.
  2. Load the project to instrument.
  3. Open the project's preferences with the menu Project > Properties.

    "Project settings on Momentics IDE 7.1"

  4. Select QNX C/C++ Project > Compiler, and in Other Options enter --cs-on. To enable the MC/DC instrumentation add also --cs-mcdc.
  5. Select QNX C/C++ Project > Linker, and in Other Options enter --cs-on.
  6. Rebuild your project to find in your build folder the instrumentation database <project_name>.csmes. You can then execute your application and import the generated .csexe file into it.

Instrumenting without modifying the project

To instrument a QNX Software Momentics project without modifying it, create a small batch file which sets the variable COVERAGESCANNER_ARGS and start the IDE.

For example:

set COVERAGESCANNER_ARGS=--cs-on
C:\QNX\QNX_Momentics_IDE\qde.exe

Then rebuild the project to instrument it.

VisualDSP

To enable the code coverage analysis, compile the project with a Coco compiler wrapper and enable the code coverage analysis during the compilation in the VisualDSP® configuration:

  1. Click Project > Project Options.
  2. In Compile > General, add --cs-on into the Additional options field.

    "Activating the code coverage analysis for the compiler"

  3. In Link > General, add --cs-on into the Additional options field.

    "Activating the code coverage analysis for the linker"

  4. Rebuild your project.

On most embedded targets, it is necessary to provide a dedicated I/O since no file systems are available for storing the code coverage information. Also, since embedded applications generally never exit, it is often necessary to implement an event handler which saves the execution report upon the reception of a specific trigger.

The simulator emulates the support of a file system. To save the coverage report on the current build directory, it is only necessary to register in the first lines of the main() a custom file I/O which uses the standard C file API.

For example:

#ifdef __COVERAGESCANNER__
static int csfputs(const char *s, void *stream) { return fputs(s, (FILE *)stream); }
static void *csfopenappend(const char *path)    { return (void*)fopen(path,"a+");  }
static int csfclose(void *fp)                   { return fclose((FILE*)fp);        }
#endif

int main()
{
#ifdef __COVERAGESCANNER__
    __coveragescanner_set_custom_io( NULL,
            csfputs,
            csfopenappend,
            NULL,
            NULL,
            csfclose,
            NULL);
#endif
....
}

To record a coverage report when a specific trigger occurs, add the following source code lines in its handler:

#ifdef __COVERAGESCANNER__
    __coveragescanner_save();
    __coveragescanner_clear();
#endif

Microsoft Visual Studio

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# Compiler

To activate the instrumentation of C# source code, it is only necessary to add the symbol COVERAGESCANNER_COVERAGE_ON in the properties of the Visual Studio .NET project. Other symbols can be appended to select additional instrumentation options. The full list can be found in Instrumenting using preprocessor symbols.

Microsoft Visual Studio .NET C and C++ Compiler

To use Coco with Visual Studio .NET:

  1. Add the location of the CoverageScanner wrappers to the first position in the VC++ Directories.
    • For Visual Studio 2005 or 2008:
      1. Start Visual Studio 2005 or 2008.
      2. Select Tools > Preferences.
      3. Select Projects > VC++ Directories.
      4. Add the entry $(SQUISHCOCO)\visualstudio as the first item in the list of directories:

        "Setting the path on Visual Studio 2005 and 2008"

    • For Visual Studio 2010:
      1. Start Visual Studio 2010.
      2. Open a C++ project.
      3. Open the project properties using the context menu of the loaded project.
      4. Select Configuration Properties > VC++ Directories.
      5. Add the entry $(SQUISHCOCO)\visualstudio as the first item in the list of executable directories:

        "Setting the path on Visual Studio 2005 and 2008"

  2. To activate code coverage analysis:
    1. Open a Visual C or C++ project.
    2. Edit the project settings by clicking Project > Properties.
    3. In Configuration Properties > C/C++ > Command Line > Additional Options, enter --cs-on:

      "C++ properties"

    4. In Configuration Properties > Linker > Command Line > Additional Options, enter --cs-libgen to specify the library to use for the generation of the CoverageScanner library.

      "Linker properties"

      For a list of recommended settings, see Library settings.

    5. For Microsoft Windows CE applications, append to the linker arguments the command line option --cs-architecture which lets you specify the target platform. For a summary of available architectures, see Architectures.

Library settings

LibraryLibrary fileCommand line option
Single ThreadedLIBC.LIB--cs-libgen=/ML
Static MultiThreadLIBCMT.LIB--cs-libgen=/MT
Dynamic Link (DLL)LIBCRT.LIB--cs-libgen=/MD
Debug Single ThreadedLIBCD.LIB--cs-libgen=/MLd
Debug Static MultiThreadLIBCMTD.LIB--cs-libgen=/MTd
Debug Dynamic Link (DLL)LIBCRTD.LIB--cs-libgen=/MDd

Architectures

Targeted architectureCommand line option
ARM Microprocessor--cs-architecture=ARM
ARM Microprocessor (Thumb code)--cs-architecture=THUMB
x86 Microprocessor--cs-architecture=IX86
MIPS16 Microprocessor--cs-architecture=MIPS16
MIPS Microprocessor--cs-architecture=MIPS
MIPS Microprocessor with FPU--cs-architecture=MIPSFPU
SH3 Microprocessor with FPU--cs-architecture=SH3
SH4 Microprocessor with FPU--cs-architecture=SH4

Microsoft Visual C++ Express

To use Coco with Microsoft Visual C++ Express:

  1. Add the location of the CoverageScanner wrappers to the first position in the VC++ Directories:
    1. Start Microsoft Visual C++ Express.
    2. Select Tools > Preferences.
    3. Select Projects > VC++ Directories.
    4. Add the entry $(SQUISHCOCO)\visualstudio as the first item in the list of directories.

      "Setting the path on Visual C++ Express"

  2. The activation of the code coverage analysis is similar to Visual Studio .NET (see Visual Studio .NET C and C++ Compiler).

Microsoft Visual Studio 6.0

To use Coco with Visual Studio 6.0:

  1. Add the location of the CoverageScanner wrappers to the first position in the executable directories:
    1. Start Visual Studio 6.0.
    2. Select Tools > Preferences > Directories.
    3. In Show directories for, select Executable files.
    4. Add the path of the directory visualstudio of the Coco installation as the first item in the list of directories. For example, if Coco is installed on c:\programme\SquishCoco, add the path c:\programme\SquishCoco\visualstudio.

      Note: Microsoft Visual Studio 6.0 does not handle system variables in the path list. So the %SQUISHCOCO% variable needs to be expanded.

      "Setting the path on Visual Studio 6.0"

  2. To activate code coverage analysis:
    1. Open a Visual C or C++ project.
    2. Edit the project settings by clicking Project > Properties.
    3. Add the option --cs-on to the additional command line arguments of the C or C++ compiler and linker.

      "Compiler properties"

    4. In the additional arguments of the linker, add --cs-libgen which specifies the name of the generated CoverageScanner library.

      "Linker properties"

      For a list of recommended settings, see Library settings.

Microsoft eMbedded Visual C++

To use Coco with Microsoft eMbedded Visual C++:

  1. Add the location of the CoverageScanner wrappers to the first position in the executable directories.
    1. Start eMbedded Visual C++.
    2. Select Tools > Preferences > Directories.
    3. In Show directories for, select Executable files.
    4. Select Platform and the targeted CPUs.
    5. Add the path of the directory WinCE of the Coco installation to the first position in the list of directories. For example: if Coco is installed on c:\programme\SquishCoco, add the path c:\programme\SquishCoco\WinCE.

      Note: Microsoft eMbedded Visual C++ does not handle system variables in the path list, so the %SQUISHCOCO% variable needs to be expanded.

      "Setting the path on eMbedded Visual C++"

  2. To activate the code coverage analysis:
    1. Open a Visual C or C++ project.
    2. Edit the project settings by clicking Project > Properties.
    3. Add the option --cs-on to the additional command line arguments of the C and C++ compiler and linker.

      "Compiler properties"

      "Linker properties"

Eclipse IDE for C/C++

In Eclipse™ IDE for C/C++, enable code coverage for a configuration by replacing the names of the compilers it uses with the names of the Coco compiler wrappers:

  1. Start Eclipse.
  2. Load the C or C++ project that should be instrumented.
  3. Open the property window Project Properties.
  4. Click C/C++ Build > Settings.
  5. Create a new configuration by clicking Manage Configurations, and select it.
  6. Click Tools Settings tab.
  7. Click GCC C++ Compiler and prepend cs to the name of the compiler.

    "Eclipse settings"

  8. Click GCC C Compiler and prepend cs to the name of the compiler.
  9. Click C++ Linker and prepend cs to the name of the linker.
  10. If it is a library project, also click GCC archiver and replace the name of the archiver command ar with csar.

Now Eclipse will use the Coco wrappers instead of the compilers when compiling.

However, the Coco wrappers are not by default in the search PATH and cannot yet be found during compilation.

To change this, a copy of the PATH variable needs to be added to the C/C++ Build > Environment section of the property window, and the path of the Coco binaries added. Under UNIX®, and with Coco installed at the default location, PATH will then have a value like /opt/SquishCoco/bin:/usr/local/bin:/usr/bin:/bin.

Almost always it will be necessary to modify the behavior of Coco by setting command line options. The easiest way to do this is by adding the variable COVERAGESCANNER_ARGS to the C/C++ Build > Environment. Its value then consists of command line options (see List of options). Code instrumentation is however already activated if this variable is not set or empty.

Note: If the value of COVERAGESCANNER_ARGS has changed, it is necessary to compile the whole project again. Otherwise, the new options have no effect.

If everything is done correctly and the project is compiled, you will see in the console window that csg++ is used instead of g++, and that a .csmes file is created next to the place of the newly-built binary. When the binary is run, a .csexe file is created in its working directory, which is typically a different directory from that of the .csmes file.

Apple Xcode

For versions up to Apple Xcode 12

To use Coco with Apple® Xcode, activate the code coverage analysis:

  1. Open a terminal window and set the CPLUSPLUS, LDPLUSPLUS, LD and CC to CoverageScanner compiler wrapper. The path of a native compiler (clang, clang++, gcc or g++) needs to be set in the PATH environment variable.
  2. Start Xcode using the open command.

    If GCC is used as compiler:

    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

    If clang is used as compiler:

    SQUISHCOCO=/Applications/SquishCoco/wrapper
export CC=$SQUISHCOCO/clang
export LD=$SQUISHCOCO/clang
export CPLUSPLUS=$SQUISHCOCO/clang++
export LDPLUSPLUS=$SQUISHCOCO/clang++
export XCODE_TOOLCHAIN_DIR=/Applications/Xcode.app/Contents/Developer/Toolchains
export XCODE_TOOLCHAIN=$XCODE_TOOLCHAIN_DIR/XcodeDefault.xctoolchain/usr/bin/

export PATH=$XCODE_TOOLCHAIN:$PATH

open /Applications/Xcode.app
  3. Open a Xcode C or C++ project.
  4. Edit the project settings by clicking Project > Edit Project Settings.
  5. Add the option --cs-on to the additional command line arguments of the C and C++ compiler in Other C Flags and Other C++ Flags and of the linker in Other Linker Flags.

    "Compiler and Linker flags"

  6. Disable the usage of the precompiled header. Open the settings of the active target (Project > Edit Active Target) and remove the contents of Prefix Header.

    "Disabling precompiled header"

For Apple Xcode 12 and above

To use Coco with Apple Xcode, activate the code coverage analysis:

  1. Open a Xcode C or C++ project.
  2. Edit the project settings by clicking the top level project.
  3. Press on the + button and insert the following User Defined Settings:
    • CC: /Applications/SquishCoco/wrapper/clang
    • CPLUSPLUS: /Applications/SquishCoco/wrapper/clang
    • LD: /Applications/SquishCoco/wrapper/clang
    • LDPLUSPLUS: /Applications/SquishCoco/wrapper/clang++
  4. Add the option --cs-on to the additional command line arguments of the C and C++ compiler in Other C Flags and Other C++ Flags and of the linker in Other Linker Flags. It is also recommended to set the path to the clang toolchain by adding the switch --cs-native-toolchain. Here is a complete example:
    --cs-on
--cs-native-toolchain=/Applications/Xcode.app/Contents/Developer/Toolchains
                      /XcodeDefault.xctoolchain/usr/bin/
  5. Disable the usage of the precompiled header. Open the settings of the active target (Project > Edit Active Target) and remove the contents of Prefix Header.

VxWorks support on Linux

To activate Coco on Wind River's Workstation:

  1. Start Wind River's Workbench
  2. Select your project in the Project Explorer window and click on the entry Properties in the context menu.
  3. Select the build properties, the compiler toolchain, and click on the Variables tab.
  4. Search for the TOOL_PATH variable and replace the /bin string at the end with /squishcoco:

    "Setting the TOOL_PATH variable"

After this change, the project can be compiled with CoverageScanner or the native toolchain. To use CoverageScanner, add the option --cs-on to the command line arguments of the compiler and the linker:

  1. Start the Wind River Workbench
  2. Select your project in the Project Explorer window and click Properties of the context menu.
  3. Select the build properties, the compiler toolchain, and click on the Tools tab.
  4. Select the entry C-Compiler in the Build Tool combo box and add to the content of the Tool Flags field the argument --cs-on:

    "Tool flags"

  5. Do the same for the C++-Compiler and the Linker tool.

With these settings, a file with the extension .vxe.csmes is generated when the code is compiled. It contains the complete instrumented code and can be inspected with CoverageBrowser. The resulting target application will then create a file with the suffix .csexe after it has run.

This file is created on the target file system. It can then be transferred to the host and imported into the .vxe.csmes file to create a report.

A video that illustrates the content of this chapter is available on https://youtube.com/watch?v=bMxMV6qHsYU.

LLVM Clang

The LLVM toolchain should already be installed. Execute the Build Environment Selection program after the installation of Coco. You can find it in the Coco installation folder with the name toolselector.exe.

In the main window, select the correct installation folder for your LLVM binary folder and click Install LLVM Support:

"Build Environment Selection"

After the installation, the Clang compiler supports CoverageScanner's command line arguments (--cs-on, --cs-hit, --cs-mcdc, and so on) and can be used to instrument C/C++ code.

IAR Embedded Workbench

Only Windows OS supported. The IAR Embedded Workbench should already be installed. Execute the Build Environment Selection program after the installation of Coco. You can find it in the Coco install folder with the name toolselector.exe.

In the main window, select the correct installation folder for your IAR binary folder and click Install IAR Support:

"Build Environment Selection"

The next step is to adjust your Embedded Workbench to execute Coco. Do this by clicking Extra Options in the project settings in Project > Options > C/C++ Compiler > Extra Options:

"Compiler Extra Options"

Enable the checkbox and type --cs-on into the field. Also add this to the linker by selecting Project > Options > Linker > Extra Options:

"Linker Extra Options"

Enable the checkbox and type --cs-on into the field. To deactivate Coco, just uncheck the two checkboxes again.

TASKING support

The TriCore Eclipse IDE from TASKING should already be installed. Execute the Build Environment Selection program after the installation of Coco. You can find it in the Coco install folder with the name toolselector.exe. In the main window, select TASKING VX-Toolset for TriCore, and click Install TASKING Support:

"Build Environment Selection"

The next step is to activate the code coverage support in the Eclipse IDE. Open TriCore Eclipse IDE, click the top of your project and in the context menu, select Properties.

In the project's configuration dialog, select C/C++ Build > Settings. The complete compiler and linker settings will be displayed. Select C/C++ Compiler > Miscellaneous. You should see then an additional argument as in the following screenshot:

"Compiler Extra Options"

Add --cs-on to enable the code coverage analysis for the compiler.

Then do the same for the linker, select Linker > Miscellaneous, and add --cs-on to the additional arguments:

"Linker Extra Options"

To instrument the embedded application, rebuild it. A .csmes file is generated upon the compilation.

But to see the coverage, it is necessary to provide a set of functions that permit uploading it to the host. The TASKING simulator supports ARM's semi-hosting function which permits writing to files directly from the target to the host's file system. You can use this to generate the execution report (.csexe file) but on real hardware, it may be necessary to use other implementations.

For the setup, add the following lines to the source containing the main function:

#include <stdio.h>

#ifdef __COVERAGESCANNER__
static int csfputs(const char *s, void *stream)
{
  return fputs(s, (FILE *)stream);
}

static void *csfopenappend(const char *path)
{
  return (void*)fopen(path,"a+");
}

static int csfclose(void *fp)
{
  return fclose((FILE*)fp);
}
#endif

Then in the first lines of the main() function, configure these functions as handlers:

int main( int argc, char *argv[] )
{
#ifdef __COVERAGESCANNER__
    __coveragescanner_set_custom_io(
        NULL,
        csfputs,
        csfopenappend,
        NULL,
        NULL,
        csfclose,
        NULL
        );
#endif

    ......
}

Then, at the location where the execution report should be saved, add the following lines:

#ifdef __COVERAGESCANNER__
    __coveragescanner_save();
#endif

Coco integration handbook Support for specific test frameworks

Coco v6.1.1 ©2023 The Qt Company Ltd.
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.