README.cppclean revision 13481:0a2c5afe5163 
1Goal:
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
12Features:
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
28AST is Abstract Syntax Tree, a representation of parsed source code.
29http://en.wikipedia.org/wiki/Abstract_syntax_tree
30
31
32System 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
38How 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
62How 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
84How 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
95Current 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
104Non-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
111Contact:
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)
116