Package: cpip
CPIPCPIP 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.FeaturesConformant C/C++ preprocessor.Gives programatic access to every preprocessing token and the state of the preprocessor at any point during preprocessing.Top level tools such asCPIPMain.pycan generate preprocessor visualisations from the command line.Requires only Python 3.6+Fully documented:https://cpip.readthedocs.io.Free software: GNU General Public License v2InstallationInstall cpip from PyPi:(CPIP)$pipinstallcpipThis will give you access to the command line entry pointcpipmain, to check this:(CPIP)$cpipmain--help...You can check CPIP on some demonstration C code, for example, from the CPIP directory there is ademodirectory.
You can process this thus:(CPIP)$cpipmain-l20-j1-odemo/output-Jdemo/sys/-Idemo/usr/demo/src/main.cpp2017-11-17 10:29:16,370 INFO     preprocessFileToOutput(): demo/src/main.cpp
2017-11-17 10:29:16,371 INFO     TU in HTML:
2017-11-17 10:29:16,372 INFO       tmp/output_normal_02/main.cpp.html
2017-11-17 10:29:16,391 INFO     preprocessFileToOutput(): Processing TU done.
2017-11-17 10:29:16,391 INFO     Macro history to:
2017-11-17 10:29:16,391 INFO       tmp/output_normal_02
2017-11-17 10:29:16,400 INFO     Include graph (SVG) to:
2017-11-17 10:29:16,401 INFO       tmp/output_normal_02/main.cpp.include.svg
2017-11-17 10:29:16,423 INFO     Writing include graph (TEXT) to:
2017-11-17 10:29:16,423 INFO       tmp/output_normal_02/main.cpp.include.svg
2017-11-17 10:29:16,424 INFO     Conditional compilation graph in HTML:
2017-11-17 10:29:16,424 INFO       tmp/output_normal_02/main.cpp.ccg.html
2017-11-17 10:29:16,431 INFO     Done: demo/src/main.cpp
2017-11-17 10:29:16,432 INFO     ITU in HTML: .../main.cpp
2017-11-17 10:29:16,448 INFO     ITU in HTML: .../system.h
2017-11-17 10:29:16,453 INFO     ITU in HTML: .../user.h
2017-11-17 10:29:16,462 INFO     preprocessFileToOutput(): demo/src/main.cpp DONE
CPU time =    0.087 (S)
Bye, bye!The result will be indemo/output/index.html.There areother installation methodsincluding directly from source.Visualising PreprocessingThe top level entry pointcpipmain(the scriptCPIPMain.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.Here is some of that output when preprocessing a single Linux kernel filecpu.c(complete output). Theindex.htmlpage shows howCPIPMain.pywas invoked[1], this has a link to to preprocessing pages for that file:This page has a single link that takes you to the landing page for the filecpu.c, at the top this links to other pages that visualise source code,#includedependencies, conditional compilation and macros:Lower down this page is a table of files that were involved in preprocessing:Visualising the Source CodeFrom thecpu.clanding page the link “Original Source” takes you to a syntax highlighted page of the original source ofcpu.c.Thecpu.clanding page link “Translation Unit” takes you to a page that shows the complete translation unit ofcpu.c(i.e. incorporating all the#includefiles). This page is annotated so that you can understand what part of the translation unit comes from which file.Visualising the#includeDependenciesThecpu.clanding page link “Normal [SVG]” takes you to a page that shows the dependencies created by#includedirectives. 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.Zooming 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:The page is dynamic and hovering over various areas provides more information:How and Why the File was IncludedHovering 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:Inc: The filename and line number of the#includedirective.As: The conditional compilation state at the point of the#includedirective.How: The text of the#includedirective followed by the directory that this file was found in, this directory is prefixed bysys=for a system include andusr=for a user include.Hovering over the filename above the file box shows the file stack (children are below parents).This 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:To see the actual count of preprocessing tokens hover over the file box:Visualising Conditional CompilationThe preprocessor is also responsible for handling conditional compilation which becomes very complicated for large projects.CPIPMain.pyproduces a succinct representation showing only the conditional directives. The links in each comment takes you to the syntax highlighted page for that file.Understanding MacrosCPIP tracks every macro definition and usage andCPIPMain.pyproduces a page that describes all the macros encountered:Each link on the page takes you to a description of the macro containing:The macro name, how many times it was referenced and whether it is still defined at the end of preprocessing.The verbatim macro definition (rewritten over several lines for long macros).File name and line number of definition, linked.Places that the macro was used, directly or indirectly. This is a table of file paths with links to the use point.Dependencies, two way:Macros that this macro invokes.Macros that invoke this macro.StatusLicenceCPIP is a C/C++ Preprocessor implemented in Python.
Copyright (C) 2008-2017 Paul RossThis program is free software; you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation; either version 2 of the License, or
(at your option) any later version.This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
GNU General Public License for more details.You should have received a copy of the GNU General Public License along
with this program; if not, write to the Free Software Foundation, Inc.,
51 Franklin Street, Fifth Floor, Boston, MA 02110-1301 USA.CreditsThis package was created withCookiecutterand theaudreyr/cookiecutter-pypackageproject template.Also many thanks toSourceForgethat hosted this project for many years.Footnotes[1]This was invoked by:$python3CPIPMain.py-kp-l20-o../../output/linux/cpu-S__STDC__=1-D__KERNEL__-D__EXPORTED_HEADERS__-DBITS_PER_LONG=64-DCONFIG_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.cHistory0.9.9 Beta Release (2022-12-16)Add strip_comments.pyAdd support for Python3 versions. Supported versions 3.6, 3.7, 3.8, 3.9, 3.10, 3.11.Remove support for Python 2.7 (although it might still work).0.9.8 Beta Release (2021-01-28)Minor fixes.0.9.7 Beta Release (2017-10-04)Minor fixes.Performance optimisations.Builds the CPython source tree in 5 hours with 2 CPUs.Documentation improvements.0.9.5 Beta Release (2017-10-03)Migrate from sourceforge to GitHub.0.9.1 (2014-09-03)Version 0.9.1, various minor fixes. Tested on Python 2.7 and 3.3.Alpha Plus Release (2014-09-04)Fairly thorough refactor. CPIP now tested on Python 2.7, 3.3. Version 0.9.1. Updated documentation.Alpha Release (2012-03-25)Very little functional change. CPIP now tested on Python 2.6, 2.7, 3.2. Added loads of documentation.Alpha Release (2011-07-14)This 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).Project started in 2008.