This operation doesn't act on the AST, but performs a peripheral operation that takes place as part of the linker process. It does use the AST, but only to find a list of source filenames.
The XRefCompiler should only be used once in a build: it reads (text formatted) xref files from the C++ parser, and writes a single compiled (Pickled) file for the formatter to use. The pickled xref file can also be used for things like CGI scripts. The xref files contain information on all* references to all symbols, including types, functions, function calls and variables.
* the completeness of the xref info is dependant on the C++ parser. At time of writing it does a pretty good job if you're not using templates, and a mediocre job when it encounters templated types or complexly overloaded functions.
The format of the output xref file, should you want to use it for a CGI script or some such, is as follows:
file = (data, index)
data = dict<scoped targetname, target_data>
index = dict<name, list<scoped targetname>>
target_data = (definitions : list<target_info>,
func calls : list<target_info>,
references : list<target_info>)
target_info = (filename, line number : int, scoped context name)The XRefCompiler has its own config sub-object under the Linker config object. The options are:
A string with a "%s" in it, that will be used to find the (text) xref files for each source file in the AST. The %s is replaced with the filename of each source file in turn, and the xref info loaded from the resulting filename. The default is "./%s-xref". Note that if you specified absolute filenames, the filenames inserted will be absolute - the default will not work in that case.
The output filename. This is a single, pickled, output file. You probably want to set the same filename in the XRefPages HTML options.
Boolean flag. By default the xref info includes information about local variables defined inside function implementations. Setting this flag to true will cause this info to be discarded from the output file. The AST has no info about local variables in any case, so they would only appear in the XRefPages and the source file pages.