Usage:

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.

----------------------------------------------------------
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".

  --gccxml-gcc-options <xxx>
       Read GCC options from file "xxx".
       This option specifies a file from which to read options to pass to the
       patched GCC C++ parser.  This is useful for specifying a long list of
       include directories.  Each line in the file becomes one option.  Empty
       lines and lines beginning in '#' are ignored.

  --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.

----------------------------------------------------------
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", "msvc7", "msvc71", or "msvc8" (if "cl" is given,
       GCC-XML attempts to guess which VS to use).

  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.

----------------------------------------------------------
GCC-XML can simulate any of the following compilers:

  GCC
       Versions 4.2, 4.1, 4.0, 3.4, 3.3, 3.2, 2.95.x

  Visual C++
       Versions 8, 7.1, 7.0, and 6 (sp5)

  Borland, Intel, SGI
       formerly supported but no longer tested

The following extra C preprocessor definitions are provided:

  -D__GCCXML__=MMmmpp
       MM, mm, and pp are the major, minor, and patch versions of GCC-XML.
       This preprocessor symbol identifies GCC-XML to the source code as it
       is preprocessed.  It can be used to enable GCC-XML-specific
       information.

  -D__GCCXML_GNUC__=M
       Defined to internal GCC parser major version.

  -D__GCCXML_GNUC_MINOR__=m
       Defined to internal GCC parser minor version.

  -D__GCCXML_GNUC_PATCHLEVEL__=p
       Defined to internal GCC parser patchlevel.

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

----------------------------------------------------------
GCC-XML has added a new attribute to the legal set of C/C++ attributes.  The
attribute is used to attach meta information to C/C++ source code, which will
then appear in the XML output.  The syntax for declaring an attribute is as
follows:

  __attribute((gccxml(<string>, <string>, ...)))
       Here <string> is a quoted string.  There must be at least one argument
       to the 'gccxml' attribute, but there is no upper limit to the total
       number of arguments.  Each argument is verified to be a string - if a
       non-string argument is found, the attribute is ignored.

The XML output for the code element that is tagged with the attribute will
then contain the following:

  attributes=" ... gccxml(<string>,<string>,<string> ...) ... "
       The 'attributes' XML attribute contains all attributes applied to the
       code element.  Each argument of the attribute is printed without
       enclosing quotes, so if an argument contains the ',' character, the
       argument will appear to be multiple arguments.

The 'gccxml' attribute can be applied to any declaration including structs,
classes, fields, parameters, methods, functions, variables, and typedefs.
The only exception is that GCC's handling of the '__attribute' language
element is currently broken for enumerations and constructors with an inlined
body.  The 'gccxml' attribute can be used any number of times on a given
declaration.

As an example of how this attribute can be used to attach meta information to
C++ declarations, consider the following macro:

  #define _out_    __attribute((gccxml("out")))
       Here '_out_' has been defined to be the gccxml attribute where the
       first argument is the string "out".  It is recommended that the first
       argument be used as a unique string name for the type of meta
       information begin applied.

Now a method declaration can be written as follows:

  void getInteger(_out_ int& i);
       This will cause the XML output to contain meta information for the
       '_out_' attribute, in the form "gccxml(out)".

Using the 'gccxml' attribute enables meta information to be included directly
within C++ source code, without the need for a custom parser to extract the
meta information.  The 'gccxml' attribute is provided for convenience only -
there is no guarantee that future versions of GCC will accept the
'__attribute' language element in a bug-free manner.