Package: scons-tool-gcccov
Support forgcccode coverage features. Note, this is not a tool for runninggcovprogram.Overviewgcc(andclang) is able to generate coverage info forgcovtool. You can usegcovto test code coverage in your programs. It helps discover where your
optimization efforts will best affect your code.gcovuses two files for profiling, seegcov files.  The names of these
files are derived from the originalobjectfile by substituting the file
suffix with either.gcno, or.gcda. The.gcnonotes file is
generated when the source file is compiled. The.gcdacount data file is
generated when a program containing object files is executed. A separate.gcdafile is created for each object file.The purpose ofscons-tool-gcccovis 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.InstallationThere are few ways to install this tool for your project.FrompypiThis method may be preferable if you build your project under a virtualenv. To
add gcccov tool frompypi, type (within your wirtualenv):pipinstallscons-tool-loaderscons-tool-gcccovor, if your project usespipenv:pipenvinstall--devscons-tool-loaderscons-tool-gcccovAlternatively, you may add this to yourPipfile[dev-packages]
scons-tool-loader = "*"
scons-tool-gcccov = "*"The tool will be installed as a namespaced packagesconstool.gcccovin project’s virtual environment. You may further usescons-tool-loaderto load the tool.As a git submoduleCreate new git repository:mkdir/tmp/prj&&cd/tmp/prjtouchREADME.rstgitinitAdd thescons-tool-gcccovas a submodule:gitsubmoduleaddgit://github.com/ptomulik/scons-tool-gcccov.gitsite_scons/site_tools/gcccovFor python 2.x create__init__.pyinsite_toolsdirectory:touchsite_scons/site_tools/__init__.pythis will allow to directly importsite_tools.gcccov(this may be required by other tools).Other projectsDownload and copy this source tree tosite_scons/site_tools/gcccov/subdirectory of your project:mkdir-psite_scons/site_tools/gcccov&&\(cdsite_scons/site_tools/gcccov&&\curl-Lhttps://github.com/ptomulik/scons-tool-gcccov/tarball/master|\tar--strip-components=1-xz)UsageSimple project with variant build and one shared libraryCreate some source files, for examplesrc/main.candsrc/bar.c:// src/main.cexternintbar();intmain(intargc,char*argv[]){returnbar();}// src/bar.cintbar(){return0;}Write the top levelSConstructfile:# SConstructenv=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'])Writesrc/SConscript:# src/SConscriptImport(['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-Qgcc-obuild/bar.os-c-g-O0--coverage-fPICsrc/bar.cgcc-obuild/libbar.so--coverage-sharedbuild/bar.osgcc-obuild/main.o-c-g-O0--coveragesrc/main.cgcc-obuild/main--coveragebuild/main.o-Lbuild-Lsrc-lbarNote the*.gcnofiles generated underbuild/directory:ptomulik@barakus:$lsbuild/*.gc*build/bar.gcnobuild/main.gcnoNow, cleanup project:ptomulik@barakus:$scons-Q-cRemovedbuild/bar.osRemovedbuild/bar.gcnoRemovedbuild/libbar.soRemovedbuild/main.oRemovedbuild/main.gcnoRemovedbuild/mainNote the*.gcnofiles get cleaned as well. Now we’ll build and run test
program:ptomulik@barakus:$scons-Qcheckgcc-obuild/main.o-c-g-O0--coveragesrc/main.cgcc-obuild/bar.os-c-g-O0--coverage-fPICsrc/bar.cgcc-obuild/libbar.so--coverage-sharedbuild/bar.osgcc-obuild/main--coveragebuild/main.o-Lbuild-Lsrc-lbarLD_LIBRARY_PATH=buildbuild/mainand list the coverage files again:ptomulik@barakus:$lsbuild/*.gc*build/bar.gcdabuild/bar.gcnobuild/main.gcdabuild/main.gcnoCleanup the project again:ptomulik@barakus:$scons-Q-cRemovedbuild/bar.osRemovedbuild/bar.gcnoRemovedbuild/bar.gcdaRemovedbuild/libbar.soRemovedbuild/main.oRemovedbuild/main.gcnoRemovedbuild/main.gcdaRemovedbuild/mainas you see, the*.gcdafiles get cleaned as well.Integrating withcxxtestIn this example we create a simple test runner usingcxxtestsuite. To drive
everything fromSCons, we’ll use ascons-tool-cxxtesttool derived from the
original SCons tool available incxxtestrepository.Installcxxtestframework:sudoapt-getinstallcxxtestCreate new git repository:mkdir/tmp/prj&&cd/tmp/prjtouchREADME.rstgitinitAddscons-tool-gcccovas submodule:gitsubmoduleaddgit://github.com/ptomulik/scons-tool-gcccov.gitsite_scons/site_tools/gcccovAddscons-tool-cxxtesttool as submodule:gitsubmoduleaddgit://github.com/ptomulik/scons-tool-cxxtest.gitsite_scons/site_tools/cxxtestCreate source filesrc/bar.cpp:// src/bar.cppintbar(){return0;}Create test filesrc/test.t.h// src/test.t.h#include<cxxtest/TestSuite.h>externintbar();classBarTestSuite1:publicCxxTest::TestSuite{public:voidtestBar(void){TS_ASSERT_EQUALS(bar(),0);}};Write the top levelSConstructfile:# SConstructimportosenv=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'])Writesrc/SConscript:# src/SConscriptImport(['env'])bar=env.SharedLibrary(['bar'],['bar.cpp'])env.CxxTest('test.t.h',LIBS=bar)Try it out:ptomulik@barakus:$LD_LIBRARY_PATH=buildscons-QcheckLoadingCxxTesttool.../usr/bin/python/usr/bin/cxxtestgen--runner=ErrorPrinter-obuild/test.cppsrc/test.t.hg++-obuild/test.o-c-g-O0--coverage-I.build/test.cppg++-obuild/bar.os-c-g-O0--coverage-fPICsrc/bar.cppg++-obuild/libbar.so--coverage-sharedbuild/bar.osg++-obuild/test--coveragebuild/test.o-Lbuild-Lsrc-lbar/tmp/prj/build/testRunningcxxtesttests(1test).OK!Check thegcovfiles created:ptomulik@barakus:$lsbuild/*.gc*build/bar.gcdabuild/bar.gcnobuild/test.gcdabuild/test.gcnoCleanup project:ptomulik@barakus:$scons-Q-cLoadingCxxTesttool...Removedbuild/bar.osRemovedbuild/bar.gcnoRemovedbuild/bar.gcdaRemovedbuild/libbar.soRemovedbuild/test.cppRemovedbuild/test.oRemovedbuild/test.gcnoRemovedbuild/test.gcdaRemovedbuild/testAs you see, all the generatedgcovside effects are cleaned up as expected.Finding out*.gcdafiles generated by a program runIf you need a list of*.gcdafiles generated when a program built with
SCons is executed, you may useGCovFindGcdaNodes: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 inthis 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.Module descriptionThe scons-tool-gcccov tool provides three methods:env.GCovInjectObjectEmitters(**overrides),env.GCovFindGcdaNodes(root),env.GCovGcdaGenerator(target, target_factory=_null, **overrides).The first method,GCovInjectObjectEmittersis the only you’ll need in most
projects. It injects special emitter to builders which create C/C++ object
files such that their corresponding*.gcnoand*.gcdafiles 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:# SConstructenv.Program('foo')env.GCovInjectObjectEmitters()and this is correct:# SConstructenv.GCovInjectObjectEmitters()env.Program('foo')The remaining two methods should not be used in normal workflow. TheGCovFindGcdaNodesdetermines what*.gcdafiles would be generated when
running certain program(s) built with SCons. TheGCovGcdaGenerator(alias)tells SCons thataliastarget generates these*.gcdafiles 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, seethis thread.
Currently it’s here only for experiments.Construction variablesThe tool uses construction variables listed in the table below:OptionDescriptionGCCCOV_DISABLEDisable gcccov functionality.GCCCOV_EXCLUDEFiles (*.gcno,*.gcda, objects, etc.) to be excluded from processing.GCCCOV_GCDA_SUFFIXSuffix for*.gcdafiles used by gcov dependency machinery.GCCCOV_GCNO_SUFFIXSuffix for*.gcnofiles used by gcov dependency machinery.GCCCOV_MAX_RECURSIONMaximum recursion depth allowed when searching for*.gcdanodes.GCCCOV_NOCLEANList of gcov files which shouldn’t be Cleaned up.GCCCOV_NOIGNOREList of gcov files which shouldn’t be Ignored from main target.GCCCOV_RUNTEST_FACTORYFactory used to build runtest target (defaults to env.ans.Alias)GCCCOV_RUNTEST_TARGETSList of targets (usually aliases) that run test runners.GCCCOV_SOURCE_SUFFIXESList of source file suffixes for which dependency injector should be enabled.GENERATING DOCUMENTATIONAPI DOCUMENTATIONYou need few prerequisites to generate API documentation:epydoc,python-docutils,python-pygments.Install them withsudoapt-getinstallpython-epydocpython-docutilspython-pygmentsThe API documentation may be generated with:sconsapi-docThe resultant html files get written tobuild/doc/apidirectory.LICENSECopyright (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