You are on page 1of 5

Name

gccxml
- Create an XML representation of C++ declarations.
Synopsis
gccxml [options] <input-file> -fxml=<output-file>
Description
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 decla
rations 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 sho
uld 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.
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 e
xecutable name and command-line arguments used to execute the patched GCC C++ pa
rser. 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 patche
d 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 t
o 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 w
ill dump only the subset of the declarations in the translation unit that is rea
chable through a sequence of source references from one of the specified startin
g 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 specifyi
ng 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 provi
ded by the UNIX man page. It is provided for use on non-UNIX platforms, but is a
lso 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 he
lp produce web pages.

--man
Print a UNIX man page and exit. This option is used by GCC-XML authors to ge
nerate the UNIX man page.
--print
Print configuration settings and exit. GCC-XML has many configuration option
s 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 wer
e going to parse the C++ source, but stop after preprocessing. This is useful fo
r 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 exec
utable.
Settings
GCC-XML is designed to simulate a compiler's parser while reading C++ source cod
e. Some configuration settings are needed to determine how to simulate a particu
lar compiler of the user's choice. The following settings can be used to configu
re GCC-XML:
GCCXML_COMPILER
The C++ compiler to be simulated. GCC-XML will attempt to automatically dete
rmine how to simulate the compiler specified by this setting. The compiler is sp
ecified 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-XM
L attempts to guess which VS to use).
GCCXML_CXXFLAGS
The flags for the C++ compiler to be simulated. The behavior of most compile
rs can be adjusted by specifying flags on the command line. When GCC-XML attempt
s to automatically determine how to simulate a compiler, these flags are taken i
nto consideration.
GCCXML_CONFIG
The configuration file for common settings. When non-default settings are of
ten used, it is convenient to write a single file containing them. When such a f
ile is specified, it will be read to configure any settings that are not yet kno
wn. Each line of the file consists of one assignment of the form KEY="VALUE" (fo
r example, GCCXML_COMPILER="g++").
GCCXML_EXECUTABLE
Specify the patched GCC C++ parser executable. The GCC-XML program as seen b
y 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 ra
rely need to change this value from its default.
GCCXML_CPP
Specify the GCC C preprocessor executable. The GCC-XML program as seen by th
e 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 purp
oses. 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 sim
ulate. Some compilers provide standard headers with code that GCC-XML cannot dir

ectly 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 includ
e 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 oth
er settings, but it can be specified directly by advanced users. Most users shou
ld 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 c
hange 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 c
orresponding 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 a
re read from the file with precedence just slightly lower than other command-lin
e 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 s
et by the environment, settings are read from the file with precedence just slig
htly lower than other environment variables.
Configuration Files
A search for GCCXML_CONFIG is performed. If GCCXML_CONFIG has not yet been s
et, 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 use
d. Finally, if a config file is found in the installation's support library dire
ctory, it will be used. Once found, any unknown settings are read from the confi
guration 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 compile
r 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 inst
allation. It configures GCC-XML to simulate the compiler that was used to build
it.
Compilers
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 pre
processor 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_F
LAGS setting. Contact the mailing list for help.
Metainfo
GCC-XML has added a new attribute to the legal set of C/C++ attributes. The attr
ibute is used to attach meta information to C/C++ source code, which will then a
ppear 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 argument
s. 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 e
lement. Each argument of the attribute is printed without enclosing quotes, so i
f an argument contains the ',' character, the argument will appear to be multipl
e arguments.
The 'gccxml' attribute can be applied to any declaration including structs, clas
ses, fields, parameters, methods, functions, variables, and typedefs. The only e
xception is that GCC's handling of the '__attribute' language element is current
ly broken for enumerations and constructors with an inlined body. The 'gccxml' a
ttribute 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 arg
ument 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_' a
ttribute, in the form "gccxml(out)".
Using the 'gccxml' attribute enables meta information to be included directly wi
thin C++ source code, without the need for a custom parser to extract the meta i

nformation. The 'gccxml' attribute is provided for convenience only - there is n


o guarantee that future versions of GCC will accept the '__attribute' language e
lement in a bug-free manner.
Copyright
GCC-XML - XML output for GCC
Copyright 2002-2007 Kitware, Inc.,
Insight Consortium
Redistribution and use in source and binary forms, with or without modification,
are permitted provided that the following conditions are met:
*
Redistributions of source code must retain the above copyright notice, this
list of conditions and the following disclaimer.
*
Redistributions in binary form must reproduce the above copyright notice, th
is list of conditions and the following disclaimer in the documentation and/or o
ther materials provided with the distribution.
*
The names of Kitware, Inc., the Insight Consortium, or the names of any cons
ortium members, or of any contributors, may not be used to endorse or promote pr
oducts derived from this software without specific prior written permission.
*
Modified source versions must be plainly marked as such, and must not be mis
represented as being the original software.
THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDER AND CONTRIBUTORS ''AS IS'' AND
ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED W
ARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED
. IN NO EVENT SHALL THE AUTHORS OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRE
CT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY
, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERW
ISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
POSSIBILITY OF SUCH DAMAGE.

You might also like