The Cpp parser preprocesses IDL, C, and C++ files. As any normal preprocessor, it will generate a file suitable as input for a C or C++ parser, i.e. it processes include and macro statements. However, it will store the encountered preprocessor directives in the ASG for further analysis.
As the list of included files may grow rather large, two mechanisms exist to restrict the number of files for which information is retained. The primary_file_only parameter is used to indicate that only the top-level file being parsed should be included. The base_path parameter, on the other hand, will restrict the number files if main_file_only is set to False. In this case, the base_path is used as a prefix, and only those file whose name starts with that prefix are marked as main.
For each included file, a SourceFile object is created and added to the parent's Include list. Further, all macro declarations, as well as macro calls, are recorded. While most useful in conjunction with the C and Cxx processors, these data can be of use stand-alone, too. For example consider a tool that reports file dependencies based on #include statements. The Dot formatter (see the section called “The Dot Formatter”) can generate a file dependency graph from the Cpp processor output alone:
Whenever the code to be parsed includes system headers, the parser needs to know about their location(s), and likely also about system macro definitions that may be in effect.
The Cpp parser provides two parameters to specify this emulation process,
compiler_flags. To illustrate their use,
let us probe for the system flags that get generated:
>synopsis --probe -p Cpp -Wp,--emulate-compiler=g++ Compiler: g++ Flags: Language: C++ Header search path: /usr/lib/gcc/i386-redhat-linux/4.1.2/../../../../include/c++/4.1.2 ... /usr/include Macro definitions: __STDC__=1 __cplusplus=1 ...
Sometimes it isn't enough to have the compiler name itself. Some flags may modify the header search path, or the predefined macros. For example, GCC can be instructed not to consider system headers at all:
>synopsis --probe -p Cpp -Wp,--emulate-compiler=g++ -Wp,compiler-flags=[\"-nostdinc\"] Compiler: g++ Flags: -nostdinc Language: C++ Header search path: Macro definitions: __STDC__=1 __cplusplus=1 ...
Here, the set of predefined header search paths is empty. Note, that the
--compiler-flags option (which, as you may remember, maps to the
compiler_flags processor parameter) expects a (Python) list.
Therefor, we use the form without the leading dashes, so we can pass Python code
as argument (See the section called “Option Handling” for details), with appropriate quoting.
For details about the parameters see the section called “Synopsis.Parsers.Cpp.Parser”.