{ "info": { "author": "Paul Ross", "author_email": "apaulross@gmail.com", "bugtrack_url": null, "classifiers": [ "Development Status :: 4 - Beta", "Environment :: Console", "Intended Audience :: Developers", "License :: OSI Approved :: GNU General Public License v2 (GPLv2)", "Natural Language :: English", "Operating System :: OS Independent", "Programming Language :: Python :: 2", "Programming Language :: Python :: 2.6", "Programming Language :: Python :: 2.7", "Programming Language :: Python :: 3", "Programming Language :: Python :: 3.3", "Programming Language :: Python :: 3.4", "Programming Language :: Python :: 3.5", "Programming Language :: Python :: 3.6" ], "description": "CPIP\n====\n\nCPIP is a C/C++ Preprocessor implemented in Python. It faithfully records all aspects of preprocessing and can produce visualisations that make debugging preprocessing far easier.\n\nFeatures\n--------\n\n* Conformant C/C++ preprocessor.\n* Gives programatic access to every preprocessing token and the state of the preprocessor at any point during preprocessing.\n* Top level tools such as ``CPIPMain.py`` can generate preprocessor visualisations from the command line.\n* Requires only Python 2.7 or 3.3+\n* Fully documented: https://cpip.readthedocs.io.\n* Free software: GNU General Public License v2\n\nInstallation\n------------\n\nYou can either clone the public repository:\n\n.. code-block:: console\n\n $ git clone git://github.com/paulross/cpip\n\nOr download the tarball:\n\n.. code-block:: console\n\n $ curl -OL https://github.com/paulross/cpip/tarball/master\n\nOnce you have a copy of the source, you can install it with:\n\n.. code-block:: console\n\n $ python setup.py install\n\nTo run the tests:\n\n.. code-block:: console\n\n $ python setup.py test\n\n\nVisualising Preprocessing\n=============================\n\nThe top level script ``CPIPMain.py`` acts like a preprocessor that generates HTML and SVG output for a source code file or directory. This output makes it easy to understand what the preprocessor is doing to your source.\n\nHere is some of that output when preprocessing a single Linux kernel file ``cpu.c`` (`complete output `_). The ``index.html`` page shows how ``CPIPMain.py`` was invoked [#f1]_, this has a link to to preprocessing pages for that file:\n\n.. Comment: Git hub does not size images so we have to have duplicates here. https://github.com/github/markup/issues/295\n\n.. image:: screenshots/HTMLLinux_cpu.c_Index.png\n :alt: CPIPMain.py's index.html landing page.\n :width: 640\n\nThis page has a single link that takes you to the landing page for the file ``cpu.c``, at the top this links to other pages that visualise source code, ``#include`` dependencies, conditional compilation and macros:\n\n.. image:: screenshots/HTMLLinux_cpu.c_Home_Top.png\n :alt: CPIP landing page after preprocessing cpu.c from the Linux kernel.\n :width: 640\n \nLower down this page is a table of files that were involved in preprocessing:\n\n.. image:: screenshots/HTMLLinux_cpu.c_Home_Lower_Lower_edit.png\n :alt: CPIP landing page after preprocessing cpu.c from the Linux kernel.\n :width: 480\n\nVisualising the Source Code\n-----------------------------\n\nFrom the ``cpu.c`` landing page the link \"Original Source\" takes you to a syntax highlighted page of the original source of ``cpu.c``.\n\n.. image:: screenshots/HTMLLinux_cpu.c_ITU_edit.png\n :alt: Annotated source code of cpu.c\n :width: 480\n\nThe ``cpu.c`` landing page link \"Translation Unit\" takes you to a page that shows the complete translation unit of ``cpu.c`` (i.e. incorporating all the ``#include`` files). This page is annotated so that you can understand what part of the translation unit comes from which file.\n\n.. image:: screenshots/HTMLLinux_cpu.c_TU_edit.png\n :alt: Annotated translation unit produced by cpu.c\n :width: 480\n\nVisualising the ``#include`` Dependencies\n---------------------------------------------\n\nThe ``cpu.c`` landing page link \"Normal [SVG]\" takes you to a page that shows the dependencies created by ``#include`` directives. This is a very rich page that represents a tree with the root at center left. ``#include``'s are in order from top to bottom. Each block represents a file, the size is proportional to the number of preprocessing tokens.\n\n.. image:: screenshots/SVG_CPU_OpeningPage_10pc.png\n :alt: Example of the file stack pop-up in the SVG include graph.\n :width: 640\n\nZooming in with the controls at the top gives more detail. If the box is coloured cyan it is because the file does not add any content to the translation unit, usually because of conditional compilation:\n\n.. image:: screenshots/SVG_CPU_FileDetail.png\n :alt: Example of the file stack pop-up in the SVG include graph.\n :width: 640\n\nThe page is dynamic and hovering over various areas provides more information:\n\nHow and Why the File was Included\n^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^\n\nHovering just to the left of the file box produces a popup that explains how the file inclusion process worked for this file, it has the following fields:\n\n* Inc: The filename and line number of the ``#include`` directive.\n* As: The conditional compilation state at the point of the ``#include`` directive.\n* How: The text of the ``#include`` directive followed by the directory that this file was found in, this directory is prefixed by ``sys=`` for a system include and ``usr=`` for a user include.\n\n.. image:: screenshots/SVGIncPath.png\n :alt: How the file got included\n :width: 640\n\nHovering over the filename above the file box shows the file stack (children are below parents).\n\n.. image:: screenshots/SVG_CPU_FileDetail_FileStack.png\n :alt: Example of the file stack pop-up in the SVG include graph.\n :width: 640\n\nThis plot can also tell you what types of preprocessor tokens were processed for each file. The coloured bars on the left of the file box indicate the proportion of preprocessing token types, the left is the file on its own, the right is the file and its child files. To understand the legend hover over those bars:\n\n.. image:: screenshots/SVG_CPU_FileDetail_HistLegend.png\n :alt: Legend for preprocessing token types.\n :width: 640\n\nTo see the actual count of preprocessing tokens hover over the file box:\n\n.. image:: screenshots/SVG_CPU_FileDetail_TokenCount.png\n :alt: Count of preprocessing token types.\n :width: 640\n\nVisualising Conditional Compilation\n--------------------------------------\n\nThe preprocessor is also responsible for handling conditional compilation which becomes very complicated for large projects. ``CPIPMain.py`` produces a succinct representation showing only the conditional directives. The links in each comment takes you to the syntax highlighted page for that file.\n\n.. image:: screenshots/HTMLLinux_cpu.c_CondComp.png\n :alt: Conditional compilation in the translation unit.\n :width: 640\n\nUnderstanding Macros\n---------------------------\n\nCPIP tracks every macro definition and usage and ``CPIPMain.py`` produces a page that describes all the macros encountered:\n\n.. image:: screenshots/HTMLLinux_cpu.c_Macro_Top.png\n :alt: The top of the macro page with down page links to details of each macro.\n :width: 640\n\nEach link on the page takes you to a description of the macro containing:\n\n* The macro name, how many times it was referenced and whether it is still defined at the end of preprocessing.\n* The verbatim macro definition (rewritten over several lines for long macros).\n* File name and line number of definition, linked.\n* Places that the macro was used, directly or indirectly. This is a table of file paths with links to the use point.\n* Dependencies, two way:\n * Macros that this macro invokes.\n * Macros that invoke this macro.\n\n.. image:: screenshots/HTMLLinux_cpu.c_Macro_Detail.png\n :alt: Macro BITMAP_LAST_WORD_MASK details: definition, where defined, where used and two way dependencies.\n :width: 640\n\nStatus\n------\n\n.. image:: https://img.shields.io/pypi/v/cpip.svg\n :target: https://pypi.python.org/pypi/cpip\n\n.. image:: https://img.shields.io/travis/paulross/cpip.svg\n :target: https://travis-ci.org/paulross/cpip\n\n.. image:: https://readthedocs.org/projects/cpip/badge/?version=latest\n :target: https://cpip.readthedocs.io/en/latest/?badge=latest\n :alt: Documentation Status\n\n.. image:: https://pyup.io/repos/github/paulross/cpip/shield.svg\n :target: https://pyup.io/repos/github/paulross/cpip/\n :alt: Updates\n\nLicence\n-------\n\nCPIP is a C/C++ Preprocessor implemented in Python.\nCopyright (C) 2008-2017 Paul Ross\n\nThis program is free software; you can redistribute it and/or modify\nit under the terms of the GNU General Public License as published by\nthe Free Software Foundation; either version 2 of the License, or\n(at your option) any later version.\n\nThis program is distributed in the hope that it will be useful,\nbut WITHOUT ANY WARRANTY; without even the implied warranty of\nMERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the\nGNU General Public License for more details.\n\nYou should have received a copy of the GNU General Public License along\nwith this program; if not, write to the Free Software Foundation, Inc.,\n51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.\n\nCredits\n---------\n\nThis package was created with Cookiecutter_ and the `audreyr/cookiecutter-pypackage`_ project template.\n\n.. _Cookiecutter: https://github.com/audreyr/cookiecutter\n.. _`audreyr/cookiecutter-pypackage`: https://github.com/audreyr/cookiecutter-pypackage\n\nAlso many thanks to `SourceForge `_ that hosted this project for many years.\n\n.. rubric:: Footnotes\n\n.. [#f1] This was invoked by:\n\n.. code-block:: sh\n\n $ python3 CPIPMain.py -kp -l20 -o ../../output/linux/cpu -S __STDC__=1 -D __KERNEL__ -D __EXPORTED_HEADERS__ -D BITS_PER_LONG=64 -D CONFIG_HZ=100 -D __x86_64__ -D __GNUC__=4 -D __has_feature(x)=0 -D __has_extension=__has_feature -D __has_attribute=__has_feature -D __has_include=__has_feature -P ~/dev/linux/linux-3.13/include/linux/kconfig.h -J /usr/include/ -J /usr/include/c++/4.2.1/ -J /usr/include/c++/4.2.1/tr1/ -J /Users/paulross/dev/linux/linux-3.13/include/ -J /Users/paulross/dev/linux/linux-3.13/include/uapi/ -J ~/dev/linux/linux-3.13/arch/x86/include/uapi/ -J ~/dev/linux/linux-3.13/arch/x86/include/ -J ~/dev/linux/linux-3.13/arch/x86/include/generated/ ~/dev/linux/linux-3.13/kernel/cpu.c\n\n\n=======\nHistory\n=======\n\n0.9.7 Beta Release (2017-10-04)\n--------------------------------\n\n* Minor fixes.\n* Performance optimisations.\n* Builds the CPython source tree in 5 hours with 2 CPUs.\n* DOcumentation improvements.\n\n0.9.5 Beta Release (2017-10-03)\n--------------------------------\n\n* Migrate from sourceforge to GitHub.\n\n0.9.1 (2014-09-03)\n------------------\n\nVersion 0.9.1, various minor fixes. Tested on Python 2.7 and 3.3.\n\nAlpha Plus Release (2014-09-04)\n-------------------------------\n\nFairly thorough refactor. CPIP now tested on Python 2.7, 3.3. Version 0.9.1. Updated documentation.\n\nAlpha Release (2012-03-25)\n---------------------------\n\nVery little functional change. CPIP now tested on Python 2.6, 2.7, 3.2. Added loads of documentation.\n\nAlpha Release (2011-07-14)\n---------------------------\n\nThis is a pre-release of CPIP. It is tested on BSD/Linux, it will probably work on Windows (although some unit tests will fail on that platform).\n\nProject started in 2008.", "description_content_type": null, "docs_url": null, "download_url": "", "downloads": { "last_day": -1, "last_month": -1, "last_week": -1 }, "home_page": "https://github.com/paulross/cpip", "keywords": "cpip", "license": "GNU General Public License v2", "maintainer": "", "maintainer_email": "", "name": "cpip", "package_url": "https://pypi.org/project/cpip/", "platform": "", "project_url": "https://pypi.org/project/cpip/", "project_urls": { "Homepage": "https://github.com/paulross/cpip" }, "release_url": "https://pypi.org/project/cpip/0.9.7/", "requires_dist": null, "requires_python": "", "summary": "CPIP is a C/C++ Preprocessor implemented in Python.", "version": "0.9.7" }, "last_serial": 3224522, "releases": { "0.9.7": [ { "comment_text": "", "digests": { "md5": "93d6a49c56a9f733c6d634c1ff75ce5a", "sha256": "86ce1ad64958fcc4537daa63c832e302d7da7d5e4935a4616555afa623cb5c2c" }, "downloads": -1, "filename": "cpip-0.9.7-py2.7.egg", "has_sig": false, "md5_digest": "93d6a49c56a9f733c6d634c1ff75ce5a", "packagetype": "bdist_egg", "python_version": "2.7", "requires_python": null, "size": 459886, "upload_time": "2017-10-04T09:55:33", "url": "https://files.pythonhosted.org/packages/2c/0b/cf3f29b52b3d6c52d056f3df354799f18a77850d3ffeaf3d501e09640dab/cpip-0.9.7-py2.7.egg" }, { "comment_text": "", "digests": { "md5": "9ed1047c1bf22b3aa0863c3c4abe9402", "sha256": "b8bf96c11b1b9b201884ae66653e0816b7fbe9f9b9f6923a06aa6f22d6a82423" }, "downloads": -1, "filename": "cpip-0.9.7-py3.6.egg", "has_sig": false, "md5_digest": "9ed1047c1bf22b3aa0863c3c4abe9402", "packagetype": "bdist_egg", "python_version": "3.6", "requires_python": null, "size": 461299, "upload_time": "2017-10-04T09:55:36", "url": "https://files.pythonhosted.org/packages/9e/3a/cc99b2778d8cb6eefcec737b2ac572e00a6b300e2e5cfffbef3b4c773d95/cpip-0.9.7-py3.6.egg" }, { "comment_text": "", "digests": { "md5": "4534cf7350eb2644c4661682281fdd8c", "sha256": "39a74df481d45b3062ac5c26449c6af48acab5d32c0646228fbfb14e56e63c45" }, "downloads": -1, "filename": "cpip-0.9.7.tar.gz", "has_sig": false, "md5_digest": "4534cf7350eb2644c4661682281fdd8c", "packagetype": "sdist", "python_version": "source", "requires_python": null, "size": 21054313, "upload_time": "2017-10-04T09:55:51", "url": "https://files.pythonhosted.org/packages/ee/3c/6a5cdebc88e263f892b998bbd1cab12a8c6f4de5a70e0b824f86d7dbe925/cpip-0.9.7.tar.gz" } ] }, "urls": [ { "comment_text": "", "digests": { "md5": "93d6a49c56a9f733c6d634c1ff75ce5a", "sha256": "86ce1ad64958fcc4537daa63c832e302d7da7d5e4935a4616555afa623cb5c2c" }, "downloads": -1, "filename": "cpip-0.9.7-py2.7.egg", "has_sig": false, "md5_digest": "93d6a49c56a9f733c6d634c1ff75ce5a", "packagetype": "bdist_egg", "python_version": "2.7", "requires_python": null, "size": 459886, "upload_time": "2017-10-04T09:55:33", "url": "https://files.pythonhosted.org/packages/2c/0b/cf3f29b52b3d6c52d056f3df354799f18a77850d3ffeaf3d501e09640dab/cpip-0.9.7-py2.7.egg" }, { "comment_text": "", "digests": { "md5": "9ed1047c1bf22b3aa0863c3c4abe9402", "sha256": "b8bf96c11b1b9b201884ae66653e0816b7fbe9f9b9f6923a06aa6f22d6a82423" }, "downloads": -1, "filename": "cpip-0.9.7-py3.6.egg", "has_sig": false, "md5_digest": "9ed1047c1bf22b3aa0863c3c4abe9402", "packagetype": "bdist_egg", "python_version": "3.6", "requires_python": null, "size": 461299, "upload_time": "2017-10-04T09:55:36", "url": "https://files.pythonhosted.org/packages/9e/3a/cc99b2778d8cb6eefcec737b2ac572e00a6b300e2e5cfffbef3b4c773d95/cpip-0.9.7-py3.6.egg" }, { "comment_text": "", "digests": { "md5": "4534cf7350eb2644c4661682281fdd8c", "sha256": "39a74df481d45b3062ac5c26449c6af48acab5d32c0646228fbfb14e56e63c45" }, "downloads": -1, "filename": "cpip-0.9.7.tar.gz", "has_sig": false, "md5_digest": "4534cf7350eb2644c4661682281fdd8c", "packagetype": "sdist", "python_version": "source", "requires_python": null, "size": 21054313, "upload_time": "2017-10-04T09:55:51", "url": "https://files.pythonhosted.org/packages/ee/3c/6a5cdebc88e263f892b998bbd1cab12a8c6f4de5a70e0b824f86d7dbe925/cpip-0.9.7.tar.gz" } ] }