How to Run GCC-XML

gccxml [options] <input-file> -fxml=<output-file>

GCC-XML parses a C++ source file as it is seen by the compiler when it is built. An easy-to-parse XML representation of the class, function, and namespace declarations is dumped to a specified file. Full C preprocessing transforms the file into a C++ translation unit as seen by the compiler. This means that GCC-XML should make use of the same standard library and other header files as the compiler. GCC-XML can be configured to simulate any of several popular compilers.

Command-line Options

The following options are available for running GCC-XML:

--copyright: Print the GCC-XML copyright and exit.
--debug: Print extra debugging information. This option causes GCC-XML to print the executable name and command-line arguments used to execute the patched GCC C++ parser. This is useful when attempting to simulate an unsupported compiler.
-fxml=<output-file>: Specify the XML output file. This option is passed directly on to the patched GCC C++ parser. It enables the XML dump and specifies the output file name.
-fxml-start=<xxx>[,...]: Specify a list of starting declarations. This option is passed directly on to the patched GCC C++ parser. It is meaningful only if -fxml= is also specified. This specifies a comma-separated list of named starting declarations. GCC-XML will dump only the subset of the declarations in the translation unit that is reachable through a sequence of source references from one of the specified starting declarations.
--gccxml-compiler <xxx>: Set GCCXML_COMPILER to "xxx".
--gccxml-cxxflags <xxx>: Set GCCXML_CXXFLAGS to "xxx".
--gccxml-executable <xxx>: Set GCCXML_EXECUTABLE to "xxx".
--gccxml-cpp <xxx>: Set GCCXML_CPP to "xxx".
--gccxml-config <xxx>: Set GCCXML_CONFIG to "xxx".
--gccxml-root <xxx>: Set GCCXML_ROOT to "xxx".
--help: Print full help and exit. Full help displays most of the documentation provided by the UNIX man page. It is provided for use on non-UNIX platforms, but is also convenient if the man page is not installed.
--help-html: Print full help in HTML format. This option is used by GCC-XML authors to help produce web pages.
--man: Print a UNIX man page and exit. This option is used by GCC-XML authors to generate the UNIX man page.
--print: Print configuration settings and exit. GCC-XML has many configuration options to help it simulate another compiler. Using this option will cause GCC-XML to configure itself as if it were going to parse the C++ source, but stop and print the configuration found. This is useful for checking the configuration.
--preprocess: Preprocess the input and exit. GCC-XML simulates the proprocessor of another compiler. Using this option will cause GCC-XML to configure itself as if it were going to parse the C++ source, but stop after preprocessing. This is useful for debugging problems related to simulation of the other compiler.
-E: Alias for --preprocess.
--version: Show program name/version banner and exit.

Other flags, such as -I and -D, are passed on to the patched GCC C++ parser executable.

Configuration Settings

GCC-XML is designed to simulate a compiler's parser while reading C++ source code. Some configuration settings are needed to determine how to simulate a particular compiler of the user's choice. The following settings can be used to configure GCC-XML:

GCCXML_COMPILER: The C++ compiler to be simulated. GCC-XML will attempt to automatically determine how to simulate the compiler specified by this setting. The compiler is specified by its executable name (such as "g++"). For Visual Studio, the compiler is specified by "msvc6" or "msvc7" (if "cl" is given, GCC-XML usually chooses msvc6 or msvc7 correctly).
GCCXML_CXXFLAGS: The flags for the C++ compiler to be simulated. The behavior of most compilers can be adjusted by specifying flags on the command line. When GCC-XML attempts to automatically determine how to simulate a compiler, these flags are taken into consideration.
GCCXML_CONFIG: The configuration file for common settings. When non-default settings are often used, it is convenient to write a single file containing them. When such a file is specified, it will be read to configure any settings that are not yet known. Each line of the file consists of one assignment of the form KEY="VALUE" (for example, GCCXML_COMPILER="g++").
GCCXML_EXECUTABLE: Specify the patched GCC C++ parser executable. The GCC-XML program as seen by the user is actually a front-end that determines the flags needed to configure the patched GCC C++ parser to simulate another compiler. This setting specifies the real executable to run once the flags have been determined. Users should rarely need to change this value from its default.
GCCXML_CPP: Specify the GCC C preprocessor executable. The GCC-XML program as seen by the user is actually a front-end that determines the flags needed to configure the patched GCC C++ parser to simulate another compiler. This setting specifies the preprocessor to run with the flags that have been determined for debugging purposes. Users should rarely need to change this value from its default.
GCCXML_ROOT: The GCC-XML support library directory. Since GCC-XML is only one C++ parser, it cannot exactly duplicate the functionality of every compiler it tries to simulate. Some compilers provide standard headers with code that GCC-XML cannot directly handle. To work around this limitation, a support library is provided for each compiler. This consists of a set of header files that are used in place of the compiler's system headers. These files contain slight tweaks and then include the corresponding real header. The root of the directory tree containing these support library headers is specified by this setting. Users should rarely need to change this value from its default.
GCCXML_FLAGS: Flags used to simulate the other compiler. When GCC-XML runs the patched GCC C++ parser, these flags are passed to the program to tell it how to simulate a particular compiler. This setting is usually detected automatically from the other settings, but it can be specified directly by advanced users. Most users should not attempt to change this value from the automatic configuration.
GCCXML_USER_FLAGS: Additional user flags for compiler simulation. When GCC-XML runs the patched GCC C++ parser, these flags are passed in addition to those specified by GCCXML_FLAGS. This allows advanced users to tweak the compiler simulation while still using the automatic configuration of GCCXML_FLAGS. Users should rarely need to change this value from its default.

There are several means by which these settings are configured. They are listed here in order of precedence (highest first):

Command-line Options: Settings can be specified by their corresponding options. When a setting's corresponding command-line option is provided, it is used in favor over any other means of configuration. If GCCXML_CONFIG is set on the command-line, settings are read from the file with precedence just slightly lower than other command-line options.
Environment Variables: Settings are configured by name in the environment. Each setting not already known is read from an environment variable with its name. If GCCXML_CONFIG is set by the environment, settings are read from the file with precedence just slightly lower than other environment variables.
Configuration Files: A search for GCCXML_CONFIG is performed. If GCCXML_CONFIG has not yet been set, an attempt is made to find a configuration file automatically. First, if the file $HOME/.gccxml/config exists, it will be used. Second, if GCC-XML is being executed from its build directory, a config file from that directory will be used. Finally, if a config file is found in the installation's support library directory, it will be used. Once found, any unknown settings are read from the configuration file.
Guessing: Guesses are made based on other settings. Once GCCXML_COMPILER has been set, it is used to automatically find the setting for GCCXML_FLAGS. If it is not set, the "CXX" environment variable is checked as a last-resort to find the compiler setting and determine GCCXML_FLAGS.

Most users should not have to adjust the defaults for these settings. There is a default GCCXML_CONFIG file provided in the support library directory after installation. It configures GCC-XML to simulate the compiler that was used to build it.

Supported Compilers

GCC-XML can simulate any of the following compilers:

GCC: Versions 3.3.x, 3.2.x, 3.1.x, 3.0.x, and 2.95.x
SGI MIPSpro: Version 7.3x
Visual C++: Versions 7.1, 7.0, and 6 (sp5)
Intel C++: Versions 7.0 and 7.1 for Linux
Borland C++: Version 5.5.x for Windows

Advanced users can simulate other compilers by manually configuring the GCCXML_FLAGS setting. Contact the mailing list for help.