Introduction

The program, cpptagdb.exe, is used to generate a lightweight program database from one or more C++ header or source files. The program database contains the following information:

• The name of the files supplied as input.
• The names of symbols defined in those files.
• The types of the symbols and the line numbers on which the symbols were defined.

The database does not contain information pertaining to function local variables and class definitions.

There is a driver script, MakeCppTags, which knows how to recursively descend through a directory structure and invoke cpptagdb.exe on the well known C++ source files so as to produce a file containing the consolidated program database named TAGPP.tagpp. The script is found in the scripts directory.

There is a corresponding program, dumpCppTagDb.exe, which prints the generated program database files in a human readable form.

Note that the editor and directory viewer are able to access the cpptagdb.exe generated information, if stored in a file named TAGPP.tagpp accessible in the ETAGS_PATH variable. These editors and viewers are able to use the information in the .tagpp file to search for symbols and files whose names are provided in partial form (using the editor's ^Xwe command. That is, if you are looking at compiler log file containing error messages, you should be able to use ^X-w-e to find the offending file in a single command. Note that you must use the "normal" format of the cpptagdb.exe program when generating the TAGPP.tagpp file (or use MakeCppTags). And you must set the ETAGS_PATH variable in your environment before starting the editor or directory viewer.

Database Formats

There are two database formats: the "grep" format and the "normal" format. the grep format is provided to make it easier from scripts to access the database. The "normal" format is meant for reading by programs that will access the data at high speeds. The grep format is bulky and the data is heavily repeated, wheras the normal format is as terse as is possible.

Consider the following C++ source file:

   Line   Text

     1    // file code.cpp
     2    
     3    class Name
     4    {
     5    public:  Name() {}
     6             int member() {}
     7    };
     8    
     9    define SYMBOL value

The grep format of the program database would look like this:

     code.cpp:3: class Name
     code.cpp:5: function Name::Name
     code.cpp:6: function Name::member
     code.cpp:9: define   SYMBOL

Whereas the normal format would look like this:

     +code.cpp
     -class Name 3
     -function Name::Name 5
     -function Name::Member 6
     -define SYMBOL 9

Command invocation

See the program's -h output for more details of command invocation.

Here is a fairly standard invocation:

    cpptagdb.exe project/include/*.h project/src/*.c*  >CppTagDb

The list of source files can be read from stdin like this:

   {
      find /dir/project/root  -name '*.h*'
      find /dir/project/root  -name '*.cpp' -o -name '*.cxx' -o -name '*.c++' -o -name '*.c'
   }  |
   cpptagdb -stdin >CppTagDb

Notes

1. This database generator is meant for well formed C++ and ANSI C source code.. The K&R style of C function declarations throw the parser off badly.

2. Because the parser is intentionally forgiving, most programs can be read successfully and will result in a proper database generation. If you use macros in your code, however, the macros can throw the parser off. The best way to guarantee proper operation is to use the compiler to generate pre-processed output text, containing line directies, and run the program on that. Macros that have an un-even number of parenthesis or curly braces are very likely to throw the parser off -- unless yo preprocess first.