{ "info": { "author": "Pawe\u0142 Tomulik", "author_email": "ptomulik@meil.pw.edu.pl", "bugtrack_url": null, "classifiers": [], "description": "scons-tool-gcccov\n=================\n\n.. image:: https://badge.fury.io/py/scons-tool-gcccov.svg\n :target: https://badge.fury.io/py/scons-tool-gcccov\n :alt: PyPi package version\n\n.. image:: https://travis-ci.org/ptomulik/scons-tool-gcccov.svg?branch=master\n :target: https://travis-ci.org/ptomulik/scons-tool-gcccov\n :alt: Travis CI build status\n\n.. image:: https://ci.appveyor.com/api/projects/status/github/ptomulik/scons-tool-gcccov?svg=true\n :target: https://ci.appveyor.com/project/ptomulik/scons-tool-gcccov\n\n\nSupport for gcc_ code coverage features. Note, this is not a tool for running\ngcov_ program.\n\nOverview\n--------\n\ngcc_ (and clang_) is able to generate coverage info for gcov_ tool. You can use\ngcov_ to test code coverage in your programs. It helps discover where your\noptimization efforts will best affect your code.\n\ngcov_ uses two files for profiling, see `gcov files`_. The names of these\nfiles are derived from the original *object* file by substituting the file\nsuffix with either ``.gcno``, or ``.gcda``. The ``.gcno`` notes file is\ngenerated when the source file is compiled. The ``.gcda`` count data file is\ngenerated when a program containing object files is executed. A separate\n``.gcda`` file is created for each object file.\n\nThe purpose of **scons-tool-gcccov** is to help to incorporate the above gcov\nfiles into project's dependency tree. Thanks to this, builders that depend on\ncoverage data (for example gcov report builders or test runners) may be\nexecuted at right moments. This also helps to clean-up coverage data when the\nproject gets cleaned up.\n\nInstallation\n------------\n\nThere are few ways to install this tool for your project.\n\nFrom pypi_\n^^^^^^^^^^\n\nThis method may be preferable if you build your project under a virtualenv. To\nadd gcccov tool from pypi_, type (within your wirtualenv):\n\n.. code-block:: shell\n\n pip install scons-tool-loader scons-tool-gcccov\n\nor, if your project uses pipenv_:\n\n.. code-block:: shell\n\n pipenv install --dev scons-tool-loader scons-tool-gcccov\n\nAlternatively, you may add this to your ``Pipfile``\n\n.. code-block::\n\n [dev-packages]\n scons-tool-loader = \"*\"\n scons-tool-gcccov = \"*\"\n\n\nThe tool will be installed as a namespaced package ``sconstool.gcccov``\nin project's virtual environment. You may further use scons-tool-loader_\nto load the tool.\n\nAs a git submodule\n^^^^^^^^^^^^^^^^^^\n\n#. Create new git repository:\n\n .. code-block:: shell\n\n mkdir /tmp/prj && cd /tmp/prj\n touch README.rst\n git init\n\n#. Add the `scons-tool-gcccov`_ as a submodule:\n\n .. code-block:: shell\n\n git submodule add git://github.com/ptomulik/scons-tool-gcccov.git site_scons/site_tools/gcccov\n\n#. For python 2.x create ``__init__.py`` in ``site_tools`` directory:\n\n .. code-block:: shell\n\n touch site_scons/site_tools/__init__.py\n\n this will allow to directly import ``site_tools.gcccov`` (this may be required by other tools).\n\nOther projects\n^^^^^^^^^^^^^^\n\n#. Download and copy this source tree to ``site_scons/site_tools/gcccov/``\n subdirectory of your project:\n\n .. code-block:: shell\n\n mkdir -p site_scons/site_tools/gcccov && \\\n (cd site_scons/site_tools/gcccov && \\\n curl -L https://github.com/ptomulik/scons-tool-gcccov/tarball/master | \\\n tar --strip-components=1 -xz)\n\nUsage\n-----\n\nSimple project with variant build and one shared library\n^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^\n\n#. Create some source files, for example ``src/main.c`` and ``src/bar.c``:\n\n .. code-block:: cpp\n\n // src/main.c\n extern int bar();\n int main(int argc, char *argv[])\n {\n return bar();\n }\n\n .. code-block:: cpp\n\n // src/bar.c\n int bar()\n {\n return 0;\n }\n\n#. Write the top level ``SConstruct`` file:\n\n .. code-block:: python\n\n # SConstruct\n env = Environment(tools = ['default', 'gcccov'])\n # Generate correct dependencies of `*.gcno' and `*.gcda' files on object\n # files being built from now on.\n env.GCovInjectObjectEmitters()\n env.Replace(CCFLAGS = ['-g', '-O0', '--coverage'], LINKFLAGS = ['--coverage'])\n SConscript('src/SConscript', variant_dir = 'build', duplicate = 0, exports = [ 'env' ])\n\n#. Write ``src/SConscript``:\n\n .. code-block:: python\n\n # src/SConscript\n Import(['env'])\n bar = env.SharedLibrary(['bar'], ['bar.c'])\n pro = env.Program('main.c', LIBS = ['bar'], LIBPATH = ['.'])\n run = env.Action(\"LD_LIBRARY_PATH=%s %s\" % (env.Dir('.').path, pro[0].path))\n env.Alias('check', pro, run)\n env.AlwaysBuild('check')\n\n#. Try it out, first we run pure build:\n\n .. code-block:: shell\n\n ptomulik@barakus:$ scons -Q\n gcc -o build/bar.os -c -g -O0 --coverage -fPIC src/bar.c\n gcc -o build/libbar.so --coverage -shared build/bar.os\n gcc -o build/main.o -c -g -O0 --coverage src/main.c\n gcc -o build/main --coverage build/main.o -Lbuild -Lsrc -lbar\n\n Note the ``*.gcno`` files generated under ``build/`` directory:\n\n .. code-block:: shell\n\n ptomulik@barakus:$ ls build/*.gc*\n build/bar.gcno build/main.gcno\n\n Now, cleanup project:\n\n .. code-block:: shell\n\n ptomulik@barakus:$ scons -Q -c\n Removed build/bar.os\n Removed build/bar.gcno\n Removed build/libbar.so\n Removed build/main.o\n Removed build/main.gcno\n Removed build/main\n\n Note the ``*.gcno`` files get cleaned as well. Now we'll build and run test\n program:\n\n .. code-block:: shell\n\n ptomulik@barakus:$ scons -Q check\n gcc -o build/main.o -c -g -O0 --coverage src/main.c\n gcc -o build/bar.os -c -g -O0 --coverage -fPIC src/bar.c\n gcc -o build/libbar.so --coverage -shared build/bar.os\n gcc -o build/main --coverage build/main.o -Lbuild -Lsrc -lbar\n LD_LIBRARY_PATH=build build/main\n\n and list the coverage files again:\n\n .. code-block:: shell\n\n ptomulik@barakus:$ ls build/*.gc*\n build/bar.gcda build/bar.gcno build/main.gcda build/main.gcno\n\n Cleanup the project again:\n\n .. code-block:: shell\n\n ptomulik@barakus:$ scons -Q -c\n Removed build/bar.os\n Removed build/bar.gcno\n Removed build/bar.gcda\n Removed build/libbar.so\n Removed build/main.o\n Removed build/main.gcno\n Removed build/main.gcda\n Removed build/main\n\n as you see, the ``*.gcda`` files get cleaned as well.\n\nIntegrating with cxxtest_\n^^^^^^^^^^^^^^^^^^^^^^^^^\n\nIn this example we create a simple test runner using cxxtest_ suite. To drive\neverything from SCons_, we'll use a scons-tool-cxxtest_ tool derived from the\noriginal SCons tool available in cxxtest_ repository.\n\n#. Install cxxtest_ framework:\n\n .. code-block:: shell\n\n sudo apt-get install cxxtest\n\n#. Create new git repository:\n\n .. code-block:: shell\n\n mkdir /tmp/prj && cd /tmp/prj\n touch README.rst\n git init\n\n#. Add **scons-tool-gcccov** as submodule:\n\n .. code-block:: shell\n\n git submodule add git://github.com/ptomulik/scons-tool-gcccov.git site_scons/site_tools/gcccov\n\n#. Add scons-tool-cxxtest_ tool as submodule:\n\n .. code-block:: shell\n\n git submodule add git://github.com/ptomulik/scons-tool-cxxtest.git site_scons/site_tools/cxxtest\n\n#. Create source file ``src/bar.cpp``:\n\n .. code-block:: cpp\n\n // src/bar.cpp\n int bar()\n {\n return 0;\n }\n\n#. Create test file ``src/test.t.h``\n\n .. code-block:: cpp\n\n // src/test.t.h\n #include \n\n extern int bar();\n class BarTestSuite1 : public CxxTest::TestSuite\n {\n public:\n void testBar(void)\n {\n TS_ASSERT_EQUALS(bar(), 0);\n }\n };\n\n#. Write the top level ``SConstruct`` file:\n\n .. code-block:: python\n\n # SConstruct\n import os\n env = Environment(ENV = os.environ, tools = ['default', 'cxxtest', 'gcccov'])\n # Generate correct dependencies of `*.gcno' and `*.gcda' files on object\n # files being built from now on.\n env.GCovInjectObjectEmitters()\n env.Replace(CCFLAGS = ['-g', '-O0', '--coverage'], LINKFLAGS = ['--coverage'])\n SConscript('src/SConscript', variant_dir = 'build', duplicate = 0, exports = [ 'env' ])\n\n#. Write ``src/SConscript``:\n\n .. code-block:: python\n\n # src/SConscript\n Import(['env'])\n bar = env.SharedLibrary(['bar'], ['bar.cpp'])\n env.CxxTest('test.t.h', LIBS = bar)\n\n#. Try it out:\n\n .. code-block:: shell\n\n ptomulik@barakus:$ LD_LIBRARY_PATH=build scons -Q check\n Loading CxxTest tool...\n /usr/bin/python /usr/bin/cxxtestgen --runner=ErrorPrinter -o build/test.cpp src/test.t.h\n g++ -o build/test.o -c -g -O0 --coverage -I. build/test.cpp\n g++ -o build/bar.os -c -g -O0 --coverage -fPIC src/bar.cpp\n g++ -o build/libbar.so --coverage -shared build/bar.os\n g++ -o build/test --coverage build/test.o -Lbuild -Lsrc -lbar\n /tmp/prj/build/test\n Running cxxtest tests (1 test).OK!\n\n#. Check the gcov_ files created:\n\n .. code-block:: shell\n\n ptomulik@barakus:$ ls build/*.gc*\n build/bar.gcda build/bar.gcno build/test.gcda build/test.gcno\n\n#. Cleanup project:\n\n .. code-block:: shell\n\n ptomulik@barakus:$ scons -Q -c\n Loading CxxTest tool...\n Removed build/bar.os\n Removed build/bar.gcno\n Removed build/bar.gcda\n Removed build/libbar.so\n Removed build/test.cpp\n Removed build/test.o\n Removed build/test.gcno\n Removed build/test.gcda\n Removed build/test\n\n As you see, all the generated gcov_ side effects are cleaned up as expected.\n\nFinding out ``*.gcda`` files generated by a program run\n^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^\n\nIf you need a list of ``*.gcda`` files generated when a program built with\nSCons is executed, you may use ``GCovFindGcdaNodes``:\n\n .. code-block:: python\n\n prog = env.Program('foo.c')\n gcda = env.GCovFindGcdaNodes(prog[0])\n\nThis method is kinda dangerous and may break some builds. It internally scans\nfor dependencies, and this is done at the time the SConscript file is\nprocessed. This may cause a problem with .sconsing file being written to wrong\ndirectory. More details are given in `this thread\n`_.\n\nAs a conclusion I would say, that you should not use it in normal workflow.\nHowever, it may be handy for development, code maintenance and such. For these\npurposes I would suggest to add special CLI options or targets to your SCons\nscript, to use it only when explicitly requested.\n\nModule description\n------------------\n\nThe scons-tool-gcccov tool provides three methods:\n\n- ``env.GCovInjectObjectEmitters(**overrides)``,\n- ``env.GCovFindGcdaNodes(root)``,\n- ``env.GCovGcdaGenerator(target, target_factory=_null, **overrides)``.\n\nThe first method, ``GCovInjectObjectEmitters`` is the only you'll need in most\nprojects. It injects special emitter to builders which create C/C++ object\nfiles such that their corresponding ``*.gcno`` and ``*.gcda`` files get added\nto dependency tree. The method should be invoked somewhere on the top of your\nSConstruct, before you specify first C/C++ file to be compiled. For example,\nthis is incorrect:\n\n .. code-block:: python\n\n # SConstruct\n env.Program('foo')\n env.GCovInjectObjectEmitters()\n\nand this is correct:\n\n .. code-block:: python\n\n # SConstruct\n env.GCovInjectObjectEmitters()\n env.Program('foo')\n\nThe remaining two methods should not be used in normal workflow. The\n``GCovFindGcdaNodes`` determines what ``*.gcda`` files would be generated when\nrunning certain program(s) built with SCons. The ``GCovGcdaGenerator(alias)``\ntells SCons that ``alias`` target generates these ``*.gcda`` files as a side\neffect (the alias should run a program/test runner and should have the program\nin its dependencies). The method should not be used currently, however, as it\nmay break some builds, see `this thread\n`_.\nCurrently it's here only for experiments.\n\nConstruction variables\n^^^^^^^^^^^^^^^^^^^^^^\n\nThe tool uses construction variables listed in the table below:\n\n========================= ==================================================================================\n Option Description\n========================= ==================================================================================\n GCCCOV_DISABLE Disable gcccov functionality.\n GCCCOV_EXCLUDE Files (``*.gcno``, ``*.gcda``, objects, etc.) to be excluded from processing.\n GCCCOV_GCDA_SUFFIX Suffix for ``*.gcda`` files used by gcov dependency machinery.\n GCCCOV_GCNO_SUFFIX Suffix for ``*.gcno`` files used by gcov dependency machinery.\n GCCCOV_MAX_RECURSION Maximum recursion depth allowed when searching for ``*.gcda`` nodes.\n GCCCOV_NOCLEAN List of gcov files which shouldn't be Cleaned up.\n GCCCOV_NOIGNORE List of gcov files which shouldn't be Ignored from main target.\n GCCCOV_RUNTEST_FACTORY Factory used to build runtest target (defaults to env.ans.Alias)\n GCCCOV_RUNTEST_TARGETS List of targets (usually aliases) that run test runners.\n GCCCOV_SOURCE_SUFFIXES List of source file suffixes for which dependency injector should be enabled.\n========================= ==================================================================================\n\nGENERATING DOCUMENTATION\n------------------------\n\nAPI DOCUMENTATION\n^^^^^^^^^^^^^^^^^\n\nYou need few prerequisites to generate API documentation:\n\n- epydoc_,\n- python-docutils_,\n- python-pygments_.\n\nInstall them with\n\n.. code-block:: shell\n\n sudo apt-get install python-epydoc python-docutils python-pygments\n\nThe API documentation may be generated with:\n\n.. code-block:: shell\n\n scons api-doc\n\nThe resultant html files get written to ``build/doc/api`` directory.\n\n\n\nLICENSE\n-------\n\nCopyright (c) 2014-2018 by Pawel Tomulik \n\nPermission is hereby granted, free of charge, to any person obtaining a copy\nof this software and associated documentation files (the \"Software\"), to deal\nin the Software without restriction, including without limitation the rights\nto use, copy, modify, merge, publish, distribute, sublicense, and/or sell\ncopies of the Software, and to permit persons to whom the Software is\nfurnished to do so, subject to the following conditions:\n\nThe above copyright notice and this permission notice shall be included in all\ncopies or substantial portions of the Software.\n\nTHE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR\nIMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,\nFITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE\nAUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER\nLIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,\nOUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE\nSOFTWARE\n\n.. \n.. _SCons: http://scons.org\n.. _gcov: http://gcc.gnu.org/onlinedocs/gcc/Gcov.html\n.. _gcc: http://gcc.gnu.org/\n.. _clang: http://clang.llvm.org/\n.. _gcov files: http://gcc.gnu.org/onlinedocs/gcc/Gcov-Data-Files.html#Gcov-Data-Files\n.. _cxxtest: http://cxxtest.com\n.. _scons-tool-gcccov: https://github.com/ptomulik/scons-tool-gcccov\n.. _scons-tool-cxxtest: https://github.com/ptomulik/scons-tool-cxxtest\n.. _scons-tool-loader: https://github.com/ptomulik/scons-tool-loader\n.. _epydoc: http://epydoc.sourceforge.net/\n.. _python-docutils: http://pypi.python.org/pypi/docutils\n.. _python-pygments: http://pygments.org/\n.. _pipenv: https://pipenv.readthedocs.io/\n.. _pypi: https://pypi.org/\n\n.. \n\n\n", "description_content_type": "text/x-rst", "docs_url": null, "download_url": "", "downloads": { "last_day": -1, "last_month": -1, "last_week": -1 }, "home_page": "https://github.com/ptomulik/scons-tool-gcccov", "keywords": "", "license": "", "maintainer": "", "maintainer_email": "", "name": "scons-tool-gcccov", "package_url": "https://pypi.org/project/scons-tool-gcccov/", "platform": "", "project_url": "https://pypi.org/project/scons-tool-gcccov/", "project_urls": { "Homepage": "https://github.com/ptomulik/scons-tool-gcccov" }, "release_url": "https://pypi.org/project/scons-tool-gcccov/0.1.2/", "requires_dist": null, "requires_python": ">=2.7", "summary": "SCons support for gcc code coverage features", "version": "0.1.2" }, "last_serial": 5176675, "releases": { "0.1.0": [ { "comment_text": "", "digests": { "md5": "72f265d3131fc283df9fda86450f50be", "sha256": "fd4ab8a6da142eb78cf3d3207f04642c80bb6600823ed32824c226d5f46887b0" }, "downloads": -1, "filename": "scons_tool_gcccov-0.1.0-py3-none-any.whl", "has_sig": false, "md5_digest": "72f265d3131fc283df9fda86450f50be", "packagetype": "bdist_wheel", "python_version": "py3", "requires_python": ">=2.7", "size": 11443, "upload_time": "2018-11-07T15:52:15", "url": "https://files.pythonhosted.org/packages/86/57/acd13ce045500d7b4f64e95e5cfda4d622808332db8c4ef538bfa7b65f68/scons_tool_gcccov-0.1.0-py3-none-any.whl" }, { "comment_text": "", "digests": { "md5": "3c8e5faa7862e8ff6a9761aa3edbc99f", "sha256": "182dff201482200c61fe0d450a8cdc80371c7ce8f4ffe0ad13e7a1af6b44695c" }, "downloads": -1, "filename": "scons-tool-gcccov-0.1.0.tar.gz", "has_sig": false, "md5_digest": "3c8e5faa7862e8ff6a9761aa3edbc99f", "packagetype": "sdist", "python_version": "source", "requires_python": ">=2.7", "size": 13191, "upload_time": "2018-11-07T15:52:17", "url": "https://files.pythonhosted.org/packages/e1/cb/32d262f16cce50dcb41298a2f1afe874bdd58bd757ad719027a3fbb435cd/scons-tool-gcccov-0.1.0.tar.gz" } ], "0.1.1": [ { "comment_text": "", "digests": { "md5": "5f24ee95131cb85cefb00b5a52ca8bce", "sha256": "496d3260c88974f70c4b27634fdd5f297e69025357d64564a5278af935b272eb" }, "downloads": -1, "filename": "scons_tool_gcccov-0.1.1-py3-none-any.whl", "has_sig": false, "md5_digest": "5f24ee95131cb85cefb00b5a52ca8bce", "packagetype": "bdist_wheel", "python_version": "py3", "requires_python": ">=2.7", "size": 11476, "upload_time": "2018-11-07T16:05:13", "url": "https://files.pythonhosted.org/packages/a5/d9/f316dcb3ca0c3070ac1a0920060add228c3769c76d91c857347a0d7998d3/scons_tool_gcccov-0.1.1-py3-none-any.whl" }, { "comment_text": "", "digests": { "md5": "8b8e2874e2d20d81454c28e553c10a5c", "sha256": "a813970b25c04a0d893a7fe7a8ffd522036c37e9ae05429b8ffabc7945668c81" }, "downloads": -1, "filename": "scons-tool-gcccov-0.1.1.tar.gz", "has_sig": false, "md5_digest": "8b8e2874e2d20d81454c28e553c10a5c", "packagetype": "sdist", "python_version": "source", "requires_python": ">=2.7", "size": 13250, "upload_time": "2018-11-07T16:05:15", "url": "https://files.pythonhosted.org/packages/50/4e/fe43be6af4f24a3ebeab7416f59ff1a3418afd4a000a345df8583ea38a86/scons-tool-gcccov-0.1.1.tar.gz" } ], "0.1.2": [ { "comment_text": "", "digests": { "md5": "0b3ce262e3235d44718ea00129f406e6", "sha256": "3411f6106854df3e939c7e6fa5f524668395e746e3ae379ea07ed5a085d7d60d" }, "downloads": -1, "filename": "scons_tool_gcccov-0.1.2-py3-none-any.whl", "has_sig": false, "md5_digest": "0b3ce262e3235d44718ea00129f406e6", "packagetype": "bdist_wheel", "python_version": "py3", "requires_python": ">=2.7", "size": 11474, "upload_time": "2019-04-23T11:13:35", "url": "https://files.pythonhosted.org/packages/52/d1/712e20428b4af66703d262f30aed074ef3cac8aa8650f333dd8eebbd2aa4/scons_tool_gcccov-0.1.2-py3-none-any.whl" }, { "comment_text": "", "digests": { "md5": "3d6dbc2178c57b121faf9c53724358b3", "sha256": "60ac09da2f0c024b87e887e8514d86358c476a5f52281102a143e369a56579fe" }, "downloads": -1, "filename": "scons-tool-gcccov-0.1.2.tar.gz", "has_sig": false, "md5_digest": "3d6dbc2178c57b121faf9c53724358b3", "packagetype": "sdist", "python_version": "source", "requires_python": ">=2.7", "size": 15581, "upload_time": "2019-04-23T11:13:36", "url": "https://files.pythonhosted.org/packages/86/9a/a8db431c4ab7939dac4deb02f18ddf35fc2bc8ee6a64ed94b00d15ab6d3d/scons-tool-gcccov-0.1.2.tar.gz" } ] }, "urls": [ { "comment_text": "", "digests": { "md5": "0b3ce262e3235d44718ea00129f406e6", "sha256": "3411f6106854df3e939c7e6fa5f524668395e746e3ae379ea07ed5a085d7d60d" }, "downloads": -1, "filename": "scons_tool_gcccov-0.1.2-py3-none-any.whl", "has_sig": false, "md5_digest": "0b3ce262e3235d44718ea00129f406e6", "packagetype": "bdist_wheel", "python_version": "py3", "requires_python": ">=2.7", "size": 11474, "upload_time": "2019-04-23T11:13:35", "url": "https://files.pythonhosted.org/packages/52/d1/712e20428b4af66703d262f30aed074ef3cac8aa8650f333dd8eebbd2aa4/scons_tool_gcccov-0.1.2-py3-none-any.whl" }, { "comment_text": "", "digests": { "md5": "3d6dbc2178c57b121faf9c53724358b3", "sha256": "60ac09da2f0c024b87e887e8514d86358c476a5f52281102a143e369a56579fe" }, "downloads": -1, "filename": "scons-tool-gcccov-0.1.2.tar.gz", "has_sig": false, "md5_digest": "3d6dbc2178c57b121faf9c53724358b3", "packagetype": "sdist", "python_version": "source", "requires_python": ">=2.7", "size": 15581, "upload_time": "2019-04-23T11:13:36", "url": "https://files.pythonhosted.org/packages/86/9a/a8db431c4ab7939dac4deb02f18ddf35fc2bc8ee6a64ed94b00d15ab6d3d/scons-tool-gcccov-0.1.2.tar.gz" } ] }