Support for IDEs and toolkits

In this chapter we give examples how Squish 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.

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

CygWin

To install the CoverageScanner compiler wrapper for GCC and G++ on CygWin, proceed as follows:

  1. Open the Build Environment Selection application. (<Windows Coco>\toolselector.exe)
  2. Select the item "CygWin - www.cygwin.com".
  3. Click on "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 Squish Coco is installed on the root file system

Note: Installation option: "1) Installation on the local machine (need to be root)" , a compiler wrapper is created for each compiler supported by Scratchbox. To invoke CoverageScanner, prepend cs to the name of the cross-compiler.

CMake

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

When Squish Coco is used with CMake, the changes are partially dependent on the tool chain that is used for compilation. We will now first describe the addition of a new build type, which is independent from the tool chain, 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 file the following lines. (The variable COVERAGE_FLAGS in the first line specifies the CoverageScanner command line options. Change its value to fit you 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, e.g. with "_DEBUG".

Microsoft Visual Studio

Under Microsoft® Visual Studio®, we need to make the new Coverage build type visible to the IDE. To do this, add to 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:

Note: This applies at least to CMake 3.2 and Microsoft® Visual Studio® 2013.

  1. Compile with Ctrl-F7. If warnings occur, they can be ignored.
  2. Make a trivial change in , like adding a space.
  3. Compile again. Then a dialog, "File modification detected", should appear. Click "Reload".

Then the list of solution configurations is updated and one can compile in coverage mode.

Compilation with Microsoft NMake

In a project that is compiled with NMake, the following must be done.

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

    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.

    Example:

    
                cmake.exe -DCMAKE_TOOLCHAIN_FILE=cl.cmake -DCMAKE_BUILD_TYPE=COVERAGE \
                          -G "NMake Makefiles" path of cmake project
                
  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.

    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.

    Example:

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

Qt Framework

Qt Creator

The following steps are needed to add instrumentation to a Qt Creator project.

  • Switch to the Projects mode using the corresponding button in the mode pane on the left side of the IDE's interface.
  • Create a custom build mode called CodeCoverage:
    • Select the Debug or Release field in the Edit build configuration combo box.
    • Click on AddClone Selected.
    • Enter CodeCoverage as new configuration name.
  • Adjust the Build directory such that the CodeCoverage configuration uses a directory different from that of the other builds.
  • In the Build Environment section, expand the System Environment pane and modify the PATH variable by prepending the path of the CoverageScanner binary:
    • macOS: /Applications/SquishCoco:<old path>
    • Linux™: /opt/SquishCoco/bin:<old path>
    • Microsoft® Windows: c:\Program Files\SquishCoco;<old path>

    Under Linux™, Squish Coco may have been installed locally. If it has been your account name is usr, use the path /home/usr/SquishCoco/bin:<old path> instead of that one in the table.

  • Select the build step qmake and add to the Additional arguments the text CONFIG+=CodeCoverage. This allows specifying additional code coverage settings by modifying the qmake's profile file ((see qmake)).
  • Select the build step Make and enter in the Additional arguments box the following text:
    • macOS: LINK=csclang++ AR=csar CXX=csclang++ CC=csclang
    • Linux™: LINK=csg++ AR=csar CXX=csg++ CC=csgcc
    • Microsoft® Windows: LINK=cscl LIB=cslib CXX=cscl CC=cscl

With these settings, a new build mode CodeCoverage has been created that creates an instrumented version of your program.

If the project has unit tests, it is possible to execute them at every build and also generate a coverage report for them. In order to do this, the following additional steps are needed.

  • In the Build Steps section, click on Add Build Step and select Custom Process Step. A new build step is created to execute the unit test the code coverage of which you are interested in. Fill in the Command box the name of the program that runs the unit tests and into the Working directory box the directory in which it should be executed. If necessary, also fill in the command line arguments of the program.
  • Add another Custom Process Step. For this step enter the full path of the cmcsexeimport tool in the Command box. In Working directory, enter the same directory as in before for the unit test program. As for the arguments of cmcsexeimport, make sure the csmes and csexe files are included. An entry in the Arguments could therefore look like
                --title="Execution" -m unit_test.csmes -P -e unit_test.csexe.

    Remember to replace the word unit_test in unit_test.csexe and unit_test.csmes with the actual name of your unit test.

  • The final Custom Process Step that needs to be added is the one for the cmreport tool, in case that report generation was wanted. Again set the Working directory as that of the unit test, and set cmreport's absolute path as the Command. Then set the arguments, e.g.:
                --title="Execution" -m unit_test.csmes --html=report

    Remember again to replace unit_test with the name of your unit test.

Now, every time you click on Build (not just Run) with this configuration, the project will be built, instrumented and optionally a report will be generated. Note that in case the project has been built before this configuration was performed, it will be required to execute the Clean Build step before building, so that the coverage measurement data will be generated.

Also keep in mind that when there was an error and one of the build steps exits with a non-zero exit status code, Qt Creator stops the build and displays the error message of the executable that failed, instead of continuing the build. This means that if a unit test fails, instead of cmcsexeimport running and importing the execution as a failed execution, cmcsexeimport does not run at all until the test case failure was fixed.

qmake

qmake is a tool to generate a Makefile in a platform-independent way, using as specification a so-called "project file". By default, qmake chooses the programs that are used for compilation. We can use the Squish Coco wrappers by setting some of qmake's variables to new values. This can be done via command line parameters or by editing the project configuration files.

Command line.

In simple cases, we can do this on the command line. There are two methods.

  • The first method works with older versions of Qt. In it, one passes the names of the Squish Coco wrappers as parameters to qmake. Under Windows this looks like
                C:\code>qmake QMAKE_LINK=cslink QMAKE_CXX=cscl QMAKE_CC=cscl

    Here we redefine the variables QMAKE_CC, QMAKE_CXX and QMAKE_LINK: They contain the name of the C compiler, the C++ compiler and the linker that are used in the Makefiles generated by qmake.

    For other platforms, the values of these variables must be replaced with the wrappers for the compilers and linker that are used there.

  • In some newer versions of Qt there is a bug in qmake that makes the previous approach unusable. In this case, one can overwrite the compiler versions later, when the Makefile generated by qmake is used for compilation. In every call of the make program, certain Makefile variables must be overwritten. Under Microsoft® Windows, the resulting command line is:
    
                C:\code>nmake LINK=cslink CXX=cscl CC=cscl other options
                

    (Under UNIX®-like systems, make must be called instead of nmake.)

Project configuration.

In more complex cases it is better to enable coverage by putting some declarations in 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 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, can use COVERAGE_OPTIONS to set coveragescanner commandline 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 adds automatically new methods to each classes 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 the Qt code itself, CoverageScanner provides the command line options --cs-qt3 for Qt3 and --cs-qt4 for Qt4 and Qt5. They are enabled by default.

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.

qbs

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

In order 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 Squish Coco with SCons, proceed as followings:

  • Prepend the path of CoverageScanner's wrapper (csgcc, cscl, …) to the PATH environment variable. The PATH environment variable should be set to be able to execute CoverageScanner wrappers .
  • Set CC, AR and LINK variable to CoverageScanner corresponding wrapper. Example: when using Microsoft® Visual Studio® compiler, set CC to cscl.exe, set LINK to cslink.exe and set AR to cslib.exe.
    • : Do no use absolute file paths to the compiler wrapper since some versions of SCons do not properly handle spaces in file names.
  • Add additional code coverage settings to the variables CCFLAGS, ARFLAGS and LINKFLAGS to exclude for example files from the instrumentation.

Here is a code snippet which can be used for Microsoft® 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 ;

In order to set correctly the build environment, it is necessary to start the build from Visual Studio's developer prompt (is available through the start menu) or Squish Coco's console provided by the "Build Environment Selection".

ARM Keil Vision

To enable the code coverage analysis it is first necessary to compile the project with Squish Coco compiler wrapper for ARM and enable the code coverage analysis during the compilation.

Processed as followings:

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

      {fig:}

      Activating the code coverage analysis for an ARM® compiler

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

      {fig:}

      Activating the code coverage analysis for an ARM® linker

Arm DS

To enable the code coverage analysis for an Arm® DS project, it is first necessary to compile it with Squish Coco compiler wrapper for ARM and enable the code coverage analysis during the compilation.

Processed as followings:

  1. To install CoverageScanner compiler wrapper for the Arm® DS tool chain, proceed as follows:
    1. Open the Build Environment Selection application. (<Windows Coco>\toolselector.exe)
    2. Select the item "ARM-DS".

      {fig:}

      Installation of Arm® DS support in Build Environment Selection.

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

      {fig:}

      Comfirmation of the installation of Arm® DS support.

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

      {fig:}

      Activating the code coverage analysis for an ARM® compiler

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

      {fig:}

      Activating the code coverage analysis for an ARM® linker

In order to upload the coverage data from the target to the host, it is necessary to 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 the 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 it using CoverageBrowser and the coverage can be analyzed as in the following screenshot:

{fig:}

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 remove 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 tool chain, proceed as follows:

  1. Open the Build Environment Selection application. (<Windows Coco>\toolselector.exe)
  2. Select the item "Green Hills".
  3. Select the directory o which the Green Hills® Software compilers are installed
  4. Click on "Install Green Hills Support" and wait for the confirmation dialog that 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 tool chain. Example: if the native tool chain is installed under c:\ghs\comp_201426, the Squish Coco compiler wrapper are installed under c:\ghs\comp_201426\squishcoco.

The compiler wrappers are replacing completely the Green Hills® Software tool chain. To activate the code coverage analysis, it is necessary to add the parameter --cs-on to the compiler arguments.

CoverageScanner Library

In order to save an execution report, it is necessary to:

  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 the following code snippet can be used (an 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 it is necessary to 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 contain.

Example: The following code write 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
    ....
    }

VisualDSP

To enable the code coverage analysis it is first necessary to compile the project with Squish Coco compiler wrapper and enable the code coverage analysis during the compilation in the VisualDSP® configuration.

Processed as followings:

  1. Click on "ProjectProject Options…"
  2. On the "Compile" tab, add --cs-on into the "Additional options" field.

    {fig:}

    Activating the code coverage analysis for the compiler

  3. On the "Link" tab, add --cs-on into the "Additional options" field.

    {fig:}

    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.

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

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

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

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 "ToolsPreferences…".
    3. Select the item "ProjectsVC++ Directories".
    4. Add the entry $(SQUISHCOCO)\visualstudio to the first position in the list of directories. (see 1.10)

      {fig:}

      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 PropertiesVC++ Directories".
    5. Add the entry $(SQUISHCOCO)\visualstudio to the first position in the list of executable directories. (see 1.11)

      {fig:}

      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 "ProjectProperties").
    3. Add to the option --cs-on to the additional command line arguments of the C or C++ compiler and linker. (see 1.12)
    4. In the additional arguments of the linker, add the --cs-libgen which specifies which library should be used for the generation of the CoverageScanner library. The table (see [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 lets you specify the target platform. The table (see [tab:architectures]) contains the list of available architectures.
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
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

{fig:}

Activation of the instrumentation under Visual Studio® .NET.

{fig:}

Activation of the instrumentation under Visual Studio® .NET.

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 "ToolsPreferences…".
    3. Select the item "ProjectsVC++ Directories".
    4. Add the entry $(SQUISHCOCO)\visualstudio to the first position in the list of directories. (see 1.14)

      {fig:}

      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 Microsoft® Visual Studio® .NET C and C++ Compiler)

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 "ToolsPreferences…".
    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

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

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

      {fig:}

      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 "ProjectProperties").
    3. Add the option --cs-on to the additional command line arguments of the C or C++ compiler and linker. (see 1.16)
    4. In the additional arguments of the linker, add the --cs-libgen which specifies the name of the generated CoverageScanner library. The table (see [tab:librarysettings]) contains the list of recommended settings.

{fig:}

Activation of the instrumentation under Visual Studio® 6.0.

{fig:}

Activation of the instrumentation under Visual Studio® 6.0.

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 "ToolsPreferences…".
    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

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

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

      {fig:}

      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 "ProjectProperties").
    3. Add the option --cs-on to the additional command line arguments of the C and C++ compiler and linker. (see 1.19)

{fig:}

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

{fig:}

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

Eclipse IDE for C/C++

In Eclipse™ IDE for C/C++, code coverage is enabled for a configuration by replacing the names of the compilers it uses with the names of the Squish Coco compiler wrappers. This can be done in the following way:

  1. Start Eclipse™.
  2. Load the C or C++ project that should be instrumented.
  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.
  10. If it is a library project, also click on "GCC archiver" and replace the name of the archiver command ar with csar.

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

{fig:}

Eclipse™ settings

However, the Squish Coco wrappers are not by default in the search part and can not yet be found during compilation.

To change this, a copy of the PATH variable needs to be added to the "C/C++ BuildEnvironment" section of the property window, and the path of the Squish Coco binaries added. Under UNIX®, and with Squish 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 Squish Coco by setting command line options. The easiest way to do this is by adding the variable COVERAGESCANNER_ARGS in "C/C++ BuildEnvironment". 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, one will see in the console window that csg++ is used instead of g++, etc., and that a .csmes file is created next to the place of the newly-built binary. When the binary then 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 older versions (up to Apple Xcode 12)

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. The path of native compiler (clang, clang++, gcc or g++) need to be present in the PATH environment variable. 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
                
  2. Open a Xcode C or C++ project.
  3. Edit the project settings (click on "ProjectEdit 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 1.22)
  5. Disable the usage of the precompiled header: Open the settings of the active target ("ProjectEdit Active Target") and remove the contains of Prefix Header.

{fig:}

Activation of the instrumentation under Apple® Xcode.

{fig:}

Deactivating precompiled headers under Apple® Xcode.

For newer versions (Apple Xcode 12 and above)

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

  1. Open a Xcode C or C++ project.
  2. Edit the project settings by clicking on 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 (fields Other C Flags and Other C++ Flags) and linker (field Other Linker Flags). (see 1.22) It is also recommended to set the path to the clang toolchain by adding the switch --cs-native-toolchain. Here 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 ("ProjectEdit Active Target") and remove the contains of Prefix Header.

VxWorks support on Linux

To activate Squish Coco on Wind River's Workstation proceed as follows:

  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 tool chain and click on the "Variables" tab.
  4. Search for the TOOL_PATH variable and replace the /bin string at the end with /squishcoco:

    {fig:}

    Setting the TOOL_PATH variable

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

To do this, proceed as followings:

  1. Start the Wind River Workbench
  2. Select your project in the "Project Explorer" window and click on "Properties" of the context menu.
  3. Select the build properties, the compiler tool chain 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:

    {fig:}

    Activating the code coverage analysis

  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 them 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 tool chain (https://releases.llvm.org/download.html) should be already installed. Execute the "Build Environment Selection" program after the installation of Squish Coco. The "Build Environment Selection" program can be found in the Squish Coco install 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

{fig:}

Build Environment Selection

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

IAR Embedded Workbench

Only Windows OS supported. The IAR Embedded Workbench should be already installed. Execute the "Build Environment Selection" program after the installation of Squish Coco. The "Build Environment Selection" program can be found 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

{fig:}

Build Environment Selection

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

{fig:}

Compiler Extra Options

Enable the checkbox and type "--cs-on" into the field. Also add this to the linker by clicking the following in the menu. Project > Options > Linker > Extra Options

{fig:}

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. The "Build Environment Selection" program can be found in the Coco install folder with the name "toolselector.exe". In the main window select "TASKING VX-Toolset for TriCore" and click on "Install TASKING Support"

{fig:}

Build Environment Selection

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

The project's configuration dialog will be opened and then select "C/C++ Build->Setting" on the side bar. The complete compiler and linker settings will be displayed. Select then "C/C++ Compiler->Miscellaneous". You should see then an additional argument as in the following screenshot:

{fig:}

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.

{fig:}

Linker Extra Options

It is then possible to instrument the embedded application by rebuilding it. A .csmes file is then generated upon the compilation.

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

For teh 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 handler:

    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

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