Usage

Help on the command line parameters can be obtained with the -h option (or without any argument) :

$ cppncss -h

Usage: cppncss [options] [file [file2 [directory [directory2] ...]]]
Version: 1.0.3

Options:
  -h                     print this message
  -d                     print debugging information
  -v                     be extra verbose
  -k                     keep going on parsing errors
  -r                     process directories recursively
  -x                     output result as xml
  -m=<measurements>      output the <measurements> sorted in given order, default is equivalent to -m=NCSS,CCN,function
  -n=<number>            output only the top <number> results
  -f=<file>              output result to <file>
  -D<symbol>[=[<value>]] replace define <symbol> with <value>
  -M<symbol>[=[<value>]] replace macro <symbol> with <value>
  -p=<path>              remove <path> prefix when displaying file names

See http://cppncss.sourceforge.net for more information.

Running

The first step is to try and parse the project code base using the -v option for verbosity and the -r option to process all files found recursively :

$ cppncss -v -r xerces-c-src_2_7_0/src

This first run will probably result in a parse error, for example :

Skipping xerces-c-src_2_7_0/src\xercesc\com\BindStatusCallback.h : Parse error (line 30, column 39)
/////////////////////////////////////////////////////////////////////////////
// BindStatCallback
class ATL_NO_VTABLE CBindStatCallback :
                                      ^

Most of the parsing errors are usually due to symbols related to defines and macros and handled by the preprocessor when compiling.
However sometimes actual coding errors can be detected.

Debugging

The -d option can be used in order to get more information about an error :

$ cppncss -d -r xerces-c-src_2_7_0/src
Parsing xerces-c-src_2_7_0/src\xercesc\com\BindStatusCallback.h
cppast.ParseException: Encountered ":" at line 30, column 39.
Was expecting one of:
    "(" ...
    ";" ...
    "," ...
    "=" ...
    "<" ...
    "::" ...
    "[" ...

Skipping xerces-c-src_2_7_0/src\xercesc\com\BindStatusCallback.h : Parse error (line 30, column 39)
/////////////////////////////////////////////////////////////////////////////
// BindStatCallback
class ATL_NO_VTABLE CBindStatCallback :
                                      ^

Note that the debug option superseeds the verbosity option so -v is no longer required.

Defines and Macros

In order to configure the preprocessing the -D (for defines) and -M (for macros) options must be used.
For example the previous parsing error can be suppressed by defining the symbol ATL_NO_VTABLE to nothing :

$ cppncss -d -r xerces-c-src_2_7_0/src -DATL_NO_VTABLE

The difference between defines and macros is that macros have arguments between parenthesis.
Most of the time macros can be accepted as function calls upon parsing, but not always.

The purpose of defines and macros is not to try and make an accurate code, actually macro parameters are even not expanded.
For example if the source contains the following macro :

MY_MACRO( "something", 12, false )

The only thing that matters is to replace it alltogether in order to obtain valid C++.
Usually simply removing a defined symbol or a macro is the easiest solution, for example in this case the following is enough :

-MMY_MACRO=

Sometimes however the symbol must be replaced by a piece of code in order to form valid C++, for example :

$ cppncss -d -r xerces-c-src_2_7_0/src -MREPORT_FACET_ERROR=; -MSTDMETHOD="void STDMETHOD"

Again the most simple solution is usually the better.

Forcing

Some of the parse errors are unavoidable, be it because of the use of non-ANSI C++ or of complex #ifdef.
Parsing can be forced to skip files containing errors and to continue the processing using the -k option.

$ cppncss -v -k -r -n=30 xerces-c-src_2_7_0/src

Usually at this point it is better to turn debugging off because of the too much verbosity it provides. Here the number of output lines are also limited to the 30 most significant results.

Prefix

Once almost all parse errors have been fixed it is time to take a look at the output.
One of the first thing to note is that file names are displayed using the full path given on the command line :

Nr. NCSS CCN File
  1 4042 1531 xerces-c-src_2_7_0/src\xercesc\validators\schema\TraverseSchema.cpp

Formatting it involves using the -p option, for example :

$ cppncss -v -k -r -n=30 xerces-c-src_2_7_0/src -p=xerces-c-src_2_7_0/src\

Will remove the given prefix from all file names, displaying instead :

Nr. NCSS CCN File
  1 4042 1531 xercesc\validators\schema\TraverseSchema.cpp

Result

In order to understand what each measurement stands for, refer to the Reference section.