README.cppclean revision 13481
113481Sgiacomo.travaglini@arm.comGoal:
213481Sgiacomo.travaglini@arm.com-----
313481Sgiacomo.travaglini@arm.com  CppClean attempts to find problems in C++ source that slow development
413481Sgiacomo.travaglini@arm.com  in large code bases, for example various forms of unused code.
513481Sgiacomo.travaglini@arm.com  Unused code can be unused functions, methods, data members, types, etc
613481Sgiacomo.travaglini@arm.com  to unnecessary #include directives.  Unnecessary #includes can cause
713481Sgiacomo.travaglini@arm.com  considerable extra compiles increasing the edit-compile-run cycle.
813481Sgiacomo.travaglini@arm.com
913481Sgiacomo.travaglini@arm.com  The project home page is:   http://code.google.com/p/cppclean/
1013481Sgiacomo.travaglini@arm.com
1113481Sgiacomo.travaglini@arm.com
1213481Sgiacomo.travaglini@arm.comFeatures:
1313481Sgiacomo.travaglini@arm.com---------
1413481Sgiacomo.travaglini@arm.com * Find and print C++ language constructs: classes, methods, functions, etc.
1513481Sgiacomo.travaglini@arm.com * Find classes with virtual methods, no virtual destructor, and no bases
1613481Sgiacomo.travaglini@arm.com * Find global/static data that are potential problems when using threads
1713481Sgiacomo.travaglini@arm.com * Unnecessary forward class declarations
1813481Sgiacomo.travaglini@arm.com * Unnecessary function declarations
1913481Sgiacomo.travaglini@arm.com * Undeclared function definitions
2013481Sgiacomo.travaglini@arm.com * (planned) Find unnecessary header files #included
2113481Sgiacomo.travaglini@arm.com   - No direct reference to anything in the header
2213481Sgiacomo.travaglini@arm.com   - Header is unnecessary if classes were forward declared instead
2313481Sgiacomo.travaglini@arm.com * (planned) Source files that reference headers not directly #included,
2413481Sgiacomo.travaglini@arm.com   ie, files that rely on a transitive #include from another header
2513481Sgiacomo.travaglini@arm.com * (planned) Unused members (private, protected, & public) methods and data
2613481Sgiacomo.travaglini@arm.com * (planned) Store AST in a SQL database so relationships can be queried
2713481Sgiacomo.travaglini@arm.com
2813481Sgiacomo.travaglini@arm.comAST is Abstract Syntax Tree, a representation of parsed source code.
2913481Sgiacomo.travaglini@arm.comhttp://en.wikipedia.org/wiki/Abstract_syntax_tree
3013481Sgiacomo.travaglini@arm.com
3113481Sgiacomo.travaglini@arm.com
3213481Sgiacomo.travaglini@arm.comSystem Requirements:
3313481Sgiacomo.travaglini@arm.com--------------------
3413481Sgiacomo.travaglini@arm.com * Python 2.4 or later (2.3 probably works too)
3513481Sgiacomo.travaglini@arm.com * Works on Windows (untested), Mac OS X, and Unix
3613481Sgiacomo.travaglini@arm.com
3713481Sgiacomo.travaglini@arm.com
3813481Sgiacomo.travaglini@arm.comHow to Run:
3913481Sgiacomo.travaglini@arm.com-----------
4013481Sgiacomo.travaglini@arm.com  For all examples, it is assumed that cppclean resides in a directory called
4113481Sgiacomo.travaglini@arm.com  /cppclean.
4213481Sgiacomo.travaglini@arm.com
4313481Sgiacomo.travaglini@arm.com  To print warnings for classes with virtual methods, no virtual destructor and
4413481Sgiacomo.travaglini@arm.com  no base classes:
4513481Sgiacomo.travaglini@arm.com
4613481Sgiacomo.travaglini@arm.com      /cppclean/run.sh nonvirtual_dtors.py file1.h file2.h file3.cc ...
4713481Sgiacomo.travaglini@arm.com
4813481Sgiacomo.travaglini@arm.com  To print all the functions defined in header file(s):
4913481Sgiacomo.travaglini@arm.com
5013481Sgiacomo.travaglini@arm.com      /cppclean/run.sh functions.py file1.h file2.h ...
5113481Sgiacomo.travaglini@arm.com
5213481Sgiacomo.travaglini@arm.com  All the commands take multiple files on the command line.  Other programs
5313481Sgiacomo.travaglini@arm.com  include: find_warnings, headers, methods, and types.  Some other programs
5413481Sgiacomo.travaglini@arm.com  are available, but used primarily for debugging.
5513481Sgiacomo.travaglini@arm.com
5613481Sgiacomo.travaglini@arm.com  run.sh is a simple wrapper that sets PYTHONPATH to /cppclean and then
5713481Sgiacomo.travaglini@arm.com  runs the program in /cppclean/cpp/PROGRAM.py.  There is currently
5813481Sgiacomo.travaglini@arm.com  no equivalent for Windows.  Contributions for a run.bat file
5913481Sgiacomo.travaglini@arm.com  would be greatly appreciated.
6013481Sgiacomo.travaglini@arm.com
6113481Sgiacomo.travaglini@arm.com
6213481Sgiacomo.travaglini@arm.comHow to Configure:
6313481Sgiacomo.travaglini@arm.com-----------------
6413481Sgiacomo.travaglini@arm.com  You can add a siteheaders.py file in /cppclean/cpp to configure where
6513481Sgiacomo.travaglini@arm.com  to look for other headers (typically -I options passed to a compiler).
6613481Sgiacomo.travaglini@arm.com  Currently two values are supported:  _TRANSITIVE and GetIncludeDirs.
6713481Sgiacomo.travaglini@arm.com  _TRANSITIVE should be set to a boolean value (True or False) indicating
6813481Sgiacomo.travaglini@arm.com  whether to transitively process all header files.  The default is False.
6913481Sgiacomo.travaglini@arm.com
7013481Sgiacomo.travaglini@arm.com  GetIncludeDirs is a function that takes a single argument and returns
7113481Sgiacomo.travaglini@arm.com  a sequence of directories to include.  This can be a generator or
7213481Sgiacomo.travaglini@arm.com  return a static list.
7313481Sgiacomo.travaglini@arm.com
7413481Sgiacomo.travaglini@arm.com      def GetIncludeDirs(filename):
7513481Sgiacomo.travaglini@arm.com          return ['/some/path/with/other/headers']
7613481Sgiacomo.travaglini@arm.com
7713481Sgiacomo.travaglini@arm.com      # Here is a more complicated example.
7813481Sgiacomo.travaglini@arm.com      def GetIncludeDirs(filename):
7913481Sgiacomo.travaglini@arm.com          yield '/path1'
8013481Sgiacomo.travaglini@arm.com          yield os.path.join('/path2', os.path.dirname(filename))
8113481Sgiacomo.travaglini@arm.com          yield '/path3'
8213481Sgiacomo.travaglini@arm.com
8313481Sgiacomo.travaglini@arm.com
8413481Sgiacomo.travaglini@arm.comHow to Test:
8513481Sgiacomo.travaglini@arm.com------------
8613481Sgiacomo.travaglini@arm.com  For all examples, it is assumed that cppclean resides in a directory called
8713481Sgiacomo.travaglini@arm.com  /cppclean.  The tests require
8813481Sgiacomo.travaglini@arm.com
8913481Sgiacomo.travaglini@arm.com  cd /cppclean
9013481Sgiacomo.travaglini@arm.com  make test
9113481Sgiacomo.travaglini@arm.com  # To generate expected results after a change:
9213481Sgiacomo.travaglini@arm.com  make expected
9313481Sgiacomo.travaglini@arm.com
9413481Sgiacomo.travaglini@arm.com
9513481Sgiacomo.travaglini@arm.comCurrent Status:
9613481Sgiacomo.travaglini@arm.com---------------
9713481Sgiacomo.travaglini@arm.com  The parser works pretty well for header files, parsing about 99% of Google's
9813481Sgiacomo.travaglini@arm.com  header files.  Anything which inspects structure of C++ source files should
9913481Sgiacomo.travaglini@arm.com  work reasonably well.  Function bodies are not transformed to an AST,
10013481Sgiacomo.travaglini@arm.com  but left as tokens.  Much work is still needed on finding unused header files
10113481Sgiacomo.travaglini@arm.com  and storing an AST in a database.
10213481Sgiacomo.travaglini@arm.com
10313481Sgiacomo.travaglini@arm.com
10413481Sgiacomo.travaglini@arm.comNon-goals:
10513481Sgiacomo.travaglini@arm.com----------
10613481Sgiacomo.travaglini@arm.com * Parsing all valid C++ source
10713481Sgiacomo.travaglini@arm.com * Handling invalid C++ source gracefully
10813481Sgiacomo.travaglini@arm.com * Compiling to machine code (or anything beyond an AST)
10913481Sgiacomo.travaglini@arm.com
11013481Sgiacomo.travaglini@arm.com
11113481Sgiacomo.travaglini@arm.comContact:
11213481Sgiacomo.travaglini@arm.com--------
11313481Sgiacomo.travaglini@arm.com  If you used cppclean, I would love to hear about your experiences
11413481Sgiacomo.travaglini@arm.com  cppclean@googlegroups.com.  Even if you don't use cppclean, I'd like to
11513481Sgiacomo.travaglini@arm.com  hear from you.  :-)  (You can contact me directly at:  nnorwitz@gmail.com)
116