From pypi

This method may be preferable if you build your project under a virtualenv. To add gcccov tool from pypi, type (within your wirtualenv):

pip install scons-tool-loader scons-tool-gcccov

or, if your project uses pipenv:

pipenv install --dev scons-tool-loader scons-tool-gcccov

Alternatively, you may add this to your Pipfile

[dev-packages]
scons-tool-loader = "*"
scons-tool-gcccov = "*"

The tool will be installed as a namespaced package sconstool.gcccov in project’s virtual environment. You may further use scons-tool-loader to load the tool.

As a git submodule

1. Create new git repository:

   mkdir /tmp/prj && cd /tmp/prj
   touch README.rst
   git init

2. Add the scons-tool-gcccov as a submodule:

   git submodule add git://github.com/ptomulik/scons-tool-gcccov.git site_scons/site_tools/gcccov

3. For python 2.x create __init__.py in site_tools directory:

   touch site_scons/site_tools/__init__.py

   this will allow to directly import site_tools.gcccov (this may be required by other tools).

Other projects

1. Download and copy this source tree to site_scons/site_tools/gcccov/ subdirectory of your project:

   mkdir -p site_scons/site_tools/gcccov && \
     (cd site_scons/site_tools/gcccov && \
       curl -L https://github.com/ptomulik/scons-tool-gcccov/tarball/master | \
       tar --strip-components=1 -xz)

Simple project with variant build and one shared library

1. Create some source files, for example src/main.c and src/bar.c:

   // src/main.c
   extern int bar();
   int main(int argc, char *argv[])
   {
     return bar();
   }

   // src/bar.c
   int bar()
   {
     return 0;
   }

2. Write the top level SConstruct file:

   # SConstruct
   env = Environment(tools = ['default', 'gcccov'])
   # Generate correct dependencies of `*.gcno' and `*.gcda' files on object
   # files being built from now on.
   env.GCovInjectObjectEmitters()
   env.Replace(CCFLAGS = ['-g', '-O0', '--coverage'], LINKFLAGS = ['--coverage'])
   SConscript('src/SConscript', variant_dir = 'build', duplicate = 0, exports = [ 'env' ])

3. Write src/SConscript:

   # src/SConscript
   Import(['env'])
   bar = env.SharedLibrary(['bar'], ['bar.c'])
   pro = env.Program('main.c', LIBS = ['bar'], LIBPATH = ['.'])
   run = env.Action("LD_LIBRARY_PATH=%s %s" % (env.Dir('.').path, pro[0].path))
   env.Alias('check', pro, run)
   env.AlwaysBuild('check')

4. Try it out, first we run pure build:

   ptomulik@barakus:$ scons -Q
   gcc -o build/bar.os -c -g -O0 --coverage -fPIC src/bar.c
   gcc -o build/libbar.so --coverage -shared build/bar.os
   gcc -o build/main.o -c -g -O0 --coverage src/main.c
   gcc -o build/main --coverage build/main.o -Lbuild -Lsrc -lbar

   Note the *.gcno files generated under build/ directory:

   ptomulik@barakus:$ ls build/*.gc*
   build/bar.gcno  build/main.gcno

   Now, cleanup project:

   ptomulik@barakus:$ scons -Q -c
   Removed build/bar.os
   Removed build/bar.gcno
   Removed build/libbar.so
   Removed build/main.o
   Removed build/main.gcno
   Removed build/main

   Note the *.gcno files get cleaned as well. Now we’ll build and run test program:

   ptomulik@barakus:$ scons -Q check
   gcc -o build/main.o -c -g -O0 --coverage src/main.c
   gcc -o build/bar.os -c -g -O0 --coverage -fPIC src/bar.c
   gcc -o build/libbar.so --coverage -shared build/bar.os
   gcc -o build/main --coverage build/main.o -Lbuild -Lsrc -lbar
   LD_LIBRARY_PATH=build build/main

   and list the coverage files again:

   ptomulik@barakus:$ ls build/*.gc*
   build/bar.gcda  build/bar.gcno  build/main.gcda  build/main.gcno

   Cleanup the project again:

   ptomulik@barakus:$ scons -Q -c
   Removed build/bar.os
   Removed build/bar.gcno
   Removed build/bar.gcda
   Removed build/libbar.so
   Removed build/main.o
   Removed build/main.gcno
   Removed build/main.gcda
   Removed build/main

   as you see, the *.gcda files get cleaned as well.

Integrating with cxxtest

In this example we create a simple test runner using cxxtest suite. To drive everything from SCons, we’ll use a scons-tool-cxxtest tool derived from the original SCons tool available in cxxtest repository.

1. Install cxxtest framework:

   sudo apt-get install cxxtest

2. Create new git repository:

   mkdir /tmp/prj && cd /tmp/prj
   touch README.rst
   git init

3. Add scons-tool-gcccov as submodule:

   git submodule add git://github.com/ptomulik/scons-tool-gcccov.git site_scons/site_tools/gcccov

4. Add scons-tool-cxxtest tool as submodule:

   git submodule add git://github.com/ptomulik/scons-tool-cxxtest.git site_scons/site_tools/cxxtest

5. Create source file src/bar.cpp:

   // src/bar.cpp
   int bar()
   {
     return 0;
   }

6. Create test file src/test.t.h

   // src/test.t.h
   #include <cxxtest/TestSuite.h>
   
   extern int bar();
   class BarTestSuite1 : public CxxTest::TestSuite
   {
   public:
       void testBar(void)
       {
           TS_ASSERT_EQUALS(bar(), 0);
       }
   };

7. Write the top level SConstruct file:

   # SConstruct
   import os
   env = Environment(ENV = os.environ, tools = ['default', 'cxxtest', 'gcccov'])
   # Generate correct dependencies of `*.gcno' and `*.gcda' files on object
   # files being built from now on.
   env.GCovInjectObjectEmitters()
   env.Replace(CCFLAGS = ['-g', '-O0', '--coverage'], LINKFLAGS = ['--coverage'])
   SConscript('src/SConscript', variant_dir = 'build', duplicate = 0, exports = [ 'env' ])

8. Write src/SConscript:

   # src/SConscript
   Import(['env'])
   bar = env.SharedLibrary(['bar'], ['bar.cpp'])
   env.CxxTest('test.t.h', LIBS = bar)

9. Try it out:

   ptomulik@barakus:$ LD_LIBRARY_PATH=build scons -Q check
   Loading CxxTest tool...
   /usr/bin/python /usr/bin/cxxtestgen --runner=ErrorPrinter -o build/test.cpp src/test.t.h
   g++ -o build/test.o -c -g -O0 --coverage -I. build/test.cpp
   g++ -o build/bar.os -c -g -O0 --coverage -fPIC src/bar.cpp
   g++ -o build/libbar.so --coverage -shared build/bar.os
   g++ -o build/test --coverage build/test.o -Lbuild -Lsrc -lbar
   /tmp/prj/build/test
   Running cxxtest tests (1 test).OK!

10. Check the gcov files created:

    ptomulik@barakus:$ ls build/*.gc*
    build/bar.gcda  build/bar.gcno  build/test.gcda  build/test.gcno

11. Cleanup project:

    ptomulik@barakus:$ scons -Q -c
    Loading CxxTest tool...
    Removed build/bar.os
    Removed build/bar.gcno
    Removed build/bar.gcda
    Removed build/libbar.so
    Removed build/test.cpp
    Removed build/test.o
    Removed build/test.gcno
    Removed build/test.gcda
    Removed build/test

    As you see, all the generated gcov side effects are cleaned up as expected.

Finding out *.gcda files generated by a program run

If you need a list of *.gcda files generated when a program built with SCons is executed, you may use GCovFindGcdaNodes:

prog = env.Program('foo.c')
gcda = env.GCovFindGcdaNodes(prog[0])

This method is kinda dangerous and may break some builds. It internally scans for dependencies, and this is done at the time the SConscript file is processed. This may cause a problem with .sconsing file being written to wrong directory. More details are given in this thread.

As a conclusion I would say, that you should not use it in normal workflow. However, it may be handy for development, code maintenance and such. For these purposes I would suggest to add special CLI options or targets to your SCons script, to use it only when explicitly requested.

Construction variables

The tool uses construction variables listed in the table below:

API DOCUMENTATION

You need few prerequisites to generate API documentation:

• epydoc,

• python-docutils,

• python-pygments.

Install them with

sudo apt-get install python-epydoc python-docutils python-pygments

The API documentation may be generated with:

scons api-doc

The resultant html files get written to build/doc/api directory.