Support for gcc code coverage features. Note, this is not a tool for running gcov program.
gcc (and clang) is able to generate coverage info for gcov tool. You can use gcov to test code coverage in your programs. It helps discover where your optimization efforts will best affect your code.
gcov uses two files for profiling, see gcov files. The names of these
files are derived from the original object file by substituting the file
suffix with either .gcno
, or .gcda
. The .gcno
notes file is
generated when the source file is compiled. The .gcda
count data file is
generated when a program containing object files is executed. A separate
.gcda
file is created for each object file.
The purpose of scons-tool-gcccov is to help to incorporate the above gcov files into project's dependency tree. Thanks to this, builders that depend on coverage data (for example gcov report builders or test runners) may be executed at right moments. This also helps to clean-up coverage data when the project gets cleaned up.
There are few ways to install this tool for your project.
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.
Create new git repository:
mkdir /tmp/prj && cd /tmp/prj touch README.rst git init
Add the scons-tool-gcccov as a submodule:
git submodule add git://github.com/ptomulik/scons-tool-gcccov.git site_scons/site_tools/gcccov
For python 2.x create
__init__.py
insite_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).
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)
Create some source files, for example
src/main.c
andsrc/bar.c
:// src/main.c extern int bar(); int main(int argc, char *argv[]) { return bar(); }
// src/bar.c int bar() { return 0; }
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' ])
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')
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 underbuild/
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.
Install cxxtest framework:
sudo apt-get install cxxtest
Create new git repository:
mkdir /tmp/prj && cd /tmp/prj touch README.rst git init
Add scons-tool-gcccov as submodule:
git submodule add git://github.com/ptomulik/scons-tool-gcccov.git site_scons/site_tools/gcccov
Add scons-tool-cxxtest tool as submodule:
git submodule add git://github.com/ptomulik/scons-tool-cxxtest.git site_scons/site_tools/cxxtest
Create source file
src/bar.cpp
:// src/bar.cpp int bar() { return 0; }
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); } };
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' ])
Write
src/SConscript
:# src/SConscript Import(['env']) bar = env.SharedLibrary(['bar'], ['bar.cpp']) env.CxxTest('test.t.h', LIBS = bar)
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!
Check the gcov files created:
ptomulik@barakus:$ ls build/*.gc* build/bar.gcda build/bar.gcno build/test.gcda build/test.gcno
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.
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.
The scons-tool-gcccov tool provides three methods:
env.GCovInjectObjectEmitters(**overrides)
,env.GCovFindGcdaNodes(root)
,env.GCovGcdaGenerator(target, target_factory=_null, **overrides)
.
The first method, GCovInjectObjectEmitters
is the only you'll need in most
projects. It injects special emitter to builders which create C/C++ object
files such that their corresponding *.gcno
and *.gcda
files get added
to dependency tree. The method should be invoked somewhere on the top of your
SConstruct, before you specify first C/C++ file to be compiled. For example,
this is incorrect:
# SConstruct env.Program('foo') env.GCovInjectObjectEmitters()
and this is correct:
# SConstruct env.GCovInjectObjectEmitters() env.Program('foo')
The remaining two methods should not be used in normal workflow. The
GCovFindGcdaNodes
determines what *.gcda
files would be generated when
running certain program(s) built with SCons. The GCovGcdaGenerator(alias)
tells SCons that alias
target generates these *.gcda
files as a side
effect (the alias should run a program/test runner and should have the program
in its dependencies). The method should not be used currently, however, as it
may break some builds, see this thread.
Currently it's here only for experiments.
The tool uses construction variables listed in the table below:
Option | Description |
---|---|
GCCCOV_DISABLE | Disable gcccov functionality. |
GCCCOV_EXCLUDE | Files (*.gcno , *.gcda , objects, etc.) to be excluded from processing. |
GCCCOV_GCDA_SUFFIX | Suffix for *.gcda files used by gcov dependency machinery. |
GCCCOV_GCNO_SUFFIX | Suffix for *.gcno files used by gcov dependency machinery. |
GCCCOV_MAX_RECURSION | Maximum recursion depth allowed when searching for *.gcda nodes. |
GCCCOV_NOCLEAN | List of gcov files which shouldn't be Cleaned up. |
GCCCOV_NOIGNORE | List of gcov files which shouldn't be Ignored from main target. |
GCCCOV_RUNTEST_FACTORY | Factory used to build runtest target (defaults to env.ans.Alias) |
GCCCOV_RUNTEST_TARGETS | List of targets (usually aliases) that run test runners. |
GCCCOV_SOURCE_SUFFIXES | List of source file suffixes for which dependency injector should be enabled. |
You need few prerequisites to generate API documentation:
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.
Copyright (c) 2014-2020 by Paweł Tomulik <ptomulik@meil.pw.edu.pl>
Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE