xenial (1) gccxml.1.gz

Provided by: gccxml_0.9.0+git20140716-6_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.

       GCC-XML - XML output for GCC

       Copyright 2002-2012 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.

       *      Neither the names of Kitware, Inc., the Insight  Software  Consortium,  nor  the  names  of  their
              contributors  may  be  used  to  endorse  or  promote  products derived from this software without
              specific prior written permission.

       THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS 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 COPYRIGHT HOLDER 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 2002-2012 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".