github.com/jlmucb/cloudproxy@v0.0.0-20170830161738-b5aa0b619bc4/src/third_party/googlemock/scripts/generator/README.cppclean (about)

     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)