GCC-XML(1)						      General Commands Manual							GCC-XML(1)

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, func-
       tion, 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.

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  exe-
	      cute 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 speci-
	      fies 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.

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", "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  con-
	      taining  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  con-
	      figuration 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 deter-
	      mine 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.

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

METAINFO

       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 with-
	      out 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  con-
       structors 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.

COPYRIGHT

       GCC-XML - XML output for GCC

       Copyright (c) 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, this list of conditions and the following disclaimer in
	      the documentation and/or other materials provided with the distribution.

       *      The names of Kitware, Inc., the Insight Consortium, or the names of any consortium members, or of any contributors, may not be  used
	      to endorse or promote products derived from this software without specific prior written permission.

       *      Modified source versions must be plainly marked as such, and must not be misrepresented 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 LIM-
       ITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL  THE  AUTHORS	OR
       CONTRIBUTORS  BE  LIABLE FOR ANY DIRECT, INDIRECT, 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 OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
       SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

       ------------------------------------------------------------

       gccxml_cc1plus - A GCC parser patched for XML dumps of translation units

       Copyright (c) 2002-2007 Kitware, Inc., Insight Consortium

       This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as  published	by
       the Free Software Foundation; either version 2 of the License, or (at your option) any later version.

       This  program  is  distributed  in  the	hope  that  it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MER-
       CHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU General Public License for more details.

       You should have received a copy of the GNU General Public License along with this program; if not, write to the
	 Free Software Foundation, Inc.
	 51 Franklin Street, Fifth Floor
	 Boston, MA  02110-1301  USA

MAILING LIST

       For help and discussion about using gccxml, a mailing list is provided at gccxml@www.gccxml.org.  Please first read the full  documentation
       at http://www.gccxml.org before posting questions to the list.

AUTHOR

       This manual page was generated by "gccxml --man".

GCC-XML 0.9.0							   July 26, 2012							GCC-XML(1)