googlemock/scripts/generator/README.cppclean

   1 Goal:
   2 -----
   3   CppClean attempts to find problems in C++ source that slow development
   4   in large code bases, for example various forms of unused code.
   5   Unused code can be unused functions, methods, data members, types, etc
   6   to unnecessary #include directives.  Unnecessary #includes can cause
   7   considerable extra compiles increasing the edit-compile-run cycle.
   8
   9   The project home page is:   http://code.google.com/p/cppclean/
  10
  11
  12 Features:
  13 ---------
  14  * Find and print C++ language constructs: classes, methods, functions, etc.
  15  * Find classes with virtual methods, no virtual destructor, and no bases
  16  * Find global/static data that are potential problems when using threads
  17  * Unnecessary forward class declarations
  18  * Unnecessary function declarations
  19  * Undeclared function definitions
  20  * (planned) Find unnecessary header files #included
  21    - No direct reference to anything in the header
  22    - Header is unnecessary if classes were forward declared instead
  23  * (planned) Source files that reference headers not directly #included,
  24    ie, files that rely on a transitive #include from another header
  25  * (planned) Unused members (private, protected, & public) methods and data
  26  * (planned) Store AST in a SQL database so relationships can be queried
  27
  28 AST is Abstract Syntax Tree, a representation of parsed source code.
  29 http://en.wikipedia.org/wiki/Abstract_syntax_tree
  30
  31
  32 System Requirements:
  33 --------------------
  34  * Python 2.4 or later (2.3 probably works too)
  35  * Works on Windows (untested), Mac OS X, and Unix
  36
  37
  38 How to Run:
  39 -----------
  40   For all examples, it is assumed that cppclean resides in a directory called
  41   /cppclean.
  42
  43   To print warnings for classes with virtual methods, no virtual destructor and
  44   no base classes:
  45
  46       /cppclean/run.sh nonvirtual_dtors.py file1.h file2.h file3.cc ...
  47
  48   To print all the functions defined in header file(s):
  49
  50       /cppclean/run.sh functions.py file1.h file2.h ...
  51
  52   All the commands take multiple files on the command line.  Other programs
  53   include: find_warnings, headers, methods, and types.  Some other programs
  54   are available, but used primarily for debugging.
  55
  56   run.sh is a simple wrapper that sets PYTHONPATH to /cppclean and then
  57   runs the program in /cppclean/cpp/PROGRAM.py.  There is currently
  58   no equivalent for Windows.  Contributions for a run.bat file
  59   would be greatly appreciated.
  60
  61
  62 How to Configure:
  63 -----------------
  64   You can add a siteheaders.py file in /cppclean/cpp to configure where
  65   to look for other headers (typically -I options passed to a compiler).
  66   Currently two values are supported:  _TRANSITIVE and GetIncludeDirs.
  67   _TRANSITIVE should be set to a boolean value (True or False) indicating
  68   whether to transitively process all header files.  The default is False.
  69
  70   GetIncludeDirs is a function that takes a single argument and returns
  71   a sequence of directories to include.  This can be a generator or
  72   return a static list.
  73
  74       def GetIncludeDirs(filename):
  75           return ['/some/path/with/other/headers']
  76
  77       # Here is a more complicated example.
  78       def GetIncludeDirs(filename):
  79           yield '/path1'
  80           yield os.path.join('/path2', os.path.dirname(filename))
  81           yield '/path3'
  82
  83
  84 How to Test:
  85 ------------
  86   For all examples, it is assumed that cppclean resides in a directory called
  87   /cppclean.  The tests require
  88
  89   cd /cppclean
  90   make test
  91   # To generate expected results after a change:
  92   make expected
  93
  94
  95 Current Status:
  96 ---------------
  97   The parser works pretty well for header files, parsing about 99% of Google's
  98   header files.  Anything which inspects structure of C++ source files should
  99   work reasonably well.  Function bodies are not transformed to an AST,
 100   but left as tokens.  Much work is still needed on finding unused header files
 101   and storing an AST in a database.
 102
 103
 104 Non-goals:
 105 ----------
 106  * Parsing all valid C++ source
 107  * Handling invalid C++ source gracefully
 108  * Compiling to machine code (or anything beyond an AST)
 109
 110
 111 Contact:
 112 --------
 113   If you used cppclean, I would love to hear about your experiences
 114   cppclean@googlegroups.com.  Even if you don't use cppclean, I'd like to
 115   hear from you.  :-)  (You can contact me directly at:  nnorwitz@gmail.com)