Provided by: gccxml_0.9.0+cvs20111013-1_amd64 bug

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

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

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

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