1GCC-XML(1) General Commands Manual GCC-XML(1)
2
6 gccxml - Create an XML representation of C++ declarations.
7
9 gccxml [options] <input-file> -fxml=<output-file>
10
12 GCC-XML parses a C++ source file as it is seen by the compiler when it
13 is built. An easy-to-parse XML representation of the class, function,
14 and namespace declarations is dumped to a specified file. Full C pre‐
15 processing transforms the file into a C++ translation unit as seen by
16 the compiler. This means that GCC-XML should make use of the same
17 standard library and other header files as the compiler. GCC-XML can
18 be configured to simulate any of several popular compilers.
19
21 The following options are available for running GCC-XML:
22 --copyright
24 Print the GCC-XML copyright and exit.
25 --debug
27 Print extra debugging information. This option causes GCC-XML
28 to print the executable name and command-line arguments used to
29 execute the patched GCC C++ parser. This is useful when
30 attempting to simulate an unsupported compiler.
31 -fxml=<output-file>
33 Specify the XML output file. This option is passed directly on
34 to the patched GCC C++ parser. It enables the XML dump and
35 specifies the output file name.
36 -fxml-start=<xxx>[,...]
38 Specify a list of starting declarations. This option is passed
39 directly on to the patched GCC C++ parser. It is meaningful
40 only if -fxml= is also specified. This specifies a comma-sepa‐
41 rated list of named starting declarations. GCC-XML will dump
42 only the subset of the declarations in the translation unit that
43 is reachable through a sequence of source references from one of
44 the specified starting declarations.
45 --gccxml-compiler <xxx>
47 Set GCCXML_COMPILER to "xxx".
48 --gccxml-cxxflags <xxx>
50 Set GCCXML_CXXFLAGS to "xxx".
51 --gccxml-executable <xxx>
53 Set GCCXML_EXECUTABLE to "xxx".
54 --gccxml-cpp <xxx>
56 Set GCCXML_CPP to "xxx".
57 --gccxml-config <xxx>
59 Set GCCXML_CONFIG to "xxx".
60 --gccxml-root <xxx>
62 Set GCCXML_ROOT to "xxx".
63 --gccxml-gcc-options <xxx>
65 Read GCC options from file "xxx". This option specifies a file
66 from which to read options to pass to the patched GCC C++
67 parser. This is useful for specifying a long list of include
68 directories. Each line in the file becomes one option. Empty
69 lines and lines beginning in '#' are ignored.
70 --help Print full help and exit. Full help displays most of the docu‐
72 mentation provided by the UNIX man page. It is provided for use
73 on non-UNIX platforms, but is also convenient if the man page is
74 not installed.
75 --help-html
77 Print full help in HTML format. This option is used by GCC-XML
78 authors to help produce web pages.
79 --man Print a UNIX man page and exit. This option is used by GCC-XML
81 authors to generate the UNIX man page.
82 --print
84 Print configuration settings and exit. GCC-XML has many config‐
85 uration options to help it simulate another compiler. Using
86 this option will cause GCC-XML to configure itself as if it were
87 going to parse the C++ source, but stop and print the configura‐
88 tion found. This is useful for checking the configuration.
89 --preprocess
91 Preprocess the input and exit. GCC-XML simulates the proproces‐
92 sor of another compiler. Using this option will cause GCC-XML
93 to configure itself as if it were going to parse the C++ source,
94 but stop after preprocessing. This is useful for debugging
95 problems related to simulation of the other compiler.
96 -E Alias for --preprocess.
98 --version
100 Show program name/version banner and exit.
101 Other flags, such as -I and -D, are passed on to the patched GCC C++
103 parser executable.
104
106 GCC-XML is designed to simulate a compiler's parser while reading C++
107 source code. Some configuration settings are needed to determine how
108 to simulate a particular compiler of the user's choice. The following
109 settings can be used to configure GCC-XML:
110 GCCXML_COMPILER
112 The C++ compiler to be simulated. GCC-XML will attempt to auto‐
113 matically determine how to simulate the compiler specified by
114 this setting. The compiler is specified by its executable name
115 (such as "g++"). For Visual Studio, the compiler is specified
116 by "msvc6", "msvc7", "msvc71", or "msvc8" (if "cl" is given,
117 GCC-XML attempts to guess which VS to use).
118 GCCXML_CXXFLAGS
120 The flags for the C++ compiler to be simulated. The behavior of
121 most compilers can be adjusted by specifying flags on the com‐
122 mand line. When GCC-XML attempts to automatically determine how
123 to simulate a compiler, these flags are taken into considera‐
124 tion.
125 GCCXML_CONFIG
127 The configuration file for common settings. When non-default
128 settings are often used, it is convenient to write a single file
129 containing them. When such a file is specified, it will be read
130 to configure any settings that are not yet known. Each line of
131 the file consists of one assignment of the form KEY="VALUE" (for
132 example, GCCXML_COMPILER="g++").
133 GCCXML_EXECUTABLE
135 Specify the patched GCC C++ parser executable. The GCC-XML pro‐
136 gram as seen by the user is actually a front-end that determines
137 the flags needed to configure the patched GCC C++ parser to sim‐
138 ulate another compiler. This setting specifies the real exe‐
139 cutable to run once the flags have been determined. Users
140 should rarely need to change this value from its default.
141 GCCXML_CPP
143 Specify the GCC C preprocessor executable. The GCC-XML program
144 as seen by the user is actually a front-end that determines the
145 flags needed to configure the patched GCC C++ parser to simulate
146 another compiler. This setting specifies the preprocessor to
147 run with the flags that have been determined for debugging pur‐
148 poses. Users should rarely need to change this value from its
149 default.
150 GCCXML_ROOT
152 The GCC-XML support library directory. Since GCC-XML is only
153 one C++ parser, it cannot exactly duplicate the functionality of
154 every compiler it tries to simulate. Some compilers provide
155 standard headers with code that GCC-XML cannot directly handle.
156 To work around this limitation, a support library is provided
157 for each compiler. This consists of a set of header files that
158 are used in place of the compiler's system headers. These files
159 contain slight tweaks and then include the corresponding real
160 header. The root of the directory tree containing these support
161 library headers is specified by this setting. Users should
162 rarely need to change this value from its default.
163 GCCXML_FLAGS
165 Flags used to simulate the other compiler. When GCC-XML runs
166 the patched GCC C++ parser, these flags are passed to the pro‐
167 gram to tell it how to simulate a particular compiler. This
168 setting is usually detected automatically from the other set‐
169 tings, but it can be specified directly by advanced users. Most
170 users should not attempt to change this value from the automatic
171 configuration.
172 GCCXML_USER_FLAGS
174 Additional user flags for compiler simulation. When GCC-XML
175 runs the patched GCC C++ parser, these flags are passed in addi‐
176 tion to those specified by GCCXML_FLAGS. This allows advanced
177 users to tweak the compiler simulation while still using the
178 automatic configuration of GCCXML_FLAGS. Users should rarely
179 need to change this value from its default.
180 There are several means by which these settings are configured. They
182 are listed here in order of precedence (highest first):
183 Command-line Options
185 Settings can be specified by their corresponding options. When
186 a setting's corresponding command-line option is provided, it is
187 used in favor over any other means of configuration. If
188 GCCXML_CONFIG is set on the command-line, settings are read from
189 the file with precedence just slightly lower than other command-
190 line options.
191 Environment Variables
193 Settings are configured by name in the environment. Each set‐
194 ting not already known is read from an environment variable with
195 its name. If GCCXML_CONFIG is set by the environment, settings
196 are read from the file with precedence just slightly lower than
197 other environment variables.
198 Configuration Files
200 A search for GCCXML_CONFIG is performed. If GCCXML_CONFIG has
201 not yet been set, an attempt is made to find a configuration
202 file automatically. First, if the file $HOME/.gccxml/config
203 exists, it will be used. Second, if GCC-XML is being executed
204 from its build directory, a config file from that directory will
205 be used. Finally, if a config file is found in the installa‐
206 tion's support library directory, it will be used. Once found,
207 any unknown settings are read from the configuration file.
208 Guessing
210 Guesses are made based on other settings. Once GCCXML_COMPILER
211 has been set, it is used to automatically find the setting for
212 GCCXML_FLAGS. If it is not set, the "CXX" environment variable
213 is checked as a last-resort to find the compiler setting and
214 determine GCCXML_FLAGS.
215 Most users should not have to adjust the defaults for these settings.
217 There is a default GCCXML_CONFIG file provided in the support library
218 directory after installation. It configures GCC-XML to simulate the
219 compiler that was used to build it.
220
222 GCC-XML can simulate any of the following compilers:
223 GCC Versions 4.2, 4.1, 4.0, 3.4, 3.3, 3.2, 2.95.x
225 Visual C++
227 Versions 8, 7.1, 7.0, and 6 (sp5)
228 Borland, Intel, SGI
230 formerly supported but no longer tested
231 The following extra C preprocessor definitions are provided:
233 -D__GCCXML__=MMmmpp
235 MM, mm, and pp are the major, minor, and patch versions of GCC-
236 XML. This preprocessor symbol identifies GCC-XML to the source
237 code as it is preprocessed. It can be used to enable GCC-XML-
238 specific information.
239 -D__GCCXML_GNUC__=M
241 Defined to internal GCC parser major version.
242 -D__GCCXML_GNUC_MINOR__=m
244 Defined to internal GCC parser minor version.
245 -D__GCCXML_GNUC_PATCHLEVEL__=p
247 Defined to internal GCC parser patchlevel.
248 Advanced users can simulate other compilers by manually configuring the
250 GCCXML_FLAGS setting. Contact the mailing list for help.
251
253 GCC-XML has added a new attribute to the legal set of C/C++ attributes.
254 The attribute is used to attach meta information to C/C++ source code,
255 which will then appear in the XML output. The syntax for declaring an
256 attribute is as follows:
257 __attribute((gccxml(<string>, <string>, ...)))
259 Here <string> is a quoted string. There must be at least one
260 argument to the 'gccxml' attribute, but there is no upper limit
261 to the total number of arguments. Each argument is verified to
262 be a string - if a non-string argument is found, the attribute
263 is ignored.
264 The XML output for the code element that is tagged with the attribute
266 will then contain the following:
267 attributes=" ... gccxml(<string>,<string>,<string> ...) ...
269 The 'attributes' XML attribute contains all attributes applied
270 to the code element. Each argument of the attribute is printed
271 without enclosing quotes, so if an argument contains the ','
272 character, the argument will appear to be multiple arguments.
273 The 'gccxml' attribute can be applied to any declaration including
275 structs, classes, fields, parameters, methods, functions, variables,
276 and typedefs. The only exception is that GCC's handling of the
277 '__attribute' language element is currently broken for enumerations and
278 constructors with an inlined body. The 'gccxml' attribute can be used
279 any number of times on a given declaration.
280 As an example of how this attribute can be used to attach meta informa‐
282 tion to C++ declarations, consider the following macro:
283 #define _out_ __attribute((gccxml("out")))
285 Here '_out_' has been defined to be the gccxml attribute where
286 the first argument is the string "out". It is recommended that
287 the first argument be used as a unique string name for the type
288 of meta information begin applied.
289 Now a method declaration can be written as follows:
291 void getInteger(_out_ int& i);
293 This will cause the XML output to contain meta information for
294 the '_out_' attribute, in the form "gccxml(out)".
295 Using the 'gccxml' attribute enables meta information to be included
297 directly within C++ source code, without the need for a custom parser
298 to extract the meta information. The 'gccxml' attribute is provided
299 for convenience only - there is no guarantee that future versions of
300 GCC will accept the '__attribute' language element in a bug-free man‐
301 ner.
302
304 GCC-XML - XML output for GCC
305 Copyright (c) 2002-2007 Kitware, Inc., Insight Consortium
308 Redistribution and use in source and binary forms, with or without mod‐
311 ification, are permitted provided that the following conditions are
312 met:
313 * Redistributions of source code must retain the above copyright
316 notice, this list of conditions and the following disclaimer.
317 * Redistributions in binary form must reproduce the above copy‐
320 right notice, this list of conditions and the following dis‐
321 claimer in the documentation and/or other materials provided
322 with the distribution.
323 * The names of Kitware, Inc., the Insight Consortium, or the names
326 of any consortium members, or of any contributors, may not be
327 used to endorse or promote products derived from this software
328 without specific prior written permission.
329 * Modified source versions must be plainly marked as such, and
332 must not be misrepresented as being the original software.
333 THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDER AND CONTRIBUTORS ``AS
336 IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
337 TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTIC‐
338 ULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE AUTHORS OR CONTRIBU‐
339 TORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEM‐
340 PLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PRO‐
341 CUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROF‐
342 ITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIA‐
343 BILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEG‐
344 LIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFT‐
345 WARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
346 ------------------------------------------------------------
349 gccxml_cc1plus - A GCC parser patched for XML dumps of translation
352 units
353 Copyright (c) 2002-2007 Kitware, Inc., Insight Consortium
356 This program is free software; you can redistribute it and/or modify it
359 under the terms of the GNU General Public License as published by the
360 Free Software Foundation; either version 2 of the License, or (at your
361 option) any later version.
362 This program is distributed in the hope that it will be useful, but
365 WITHOUT ANY WARRANTY; without even the implied warranty of MER‐
366 CHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General
367 Public License for more details.
368 You should have received a copy of the GNU General Public License along
371 with this program; if not, write to the
372 Free Software Foundation, Inc.
373 51 Franklin Street, Fifth Floor
374 Boston, MA 02110-1301 USA
375
378 For help and discussion about using gccxml, a mailing list is provided
379 at gccxml@www.gccxml.org. Please first read the full documentation at
380 http://www.gccxml.org before posting questions to the list.
381
383 This manual page was generated by "gccxml --man".
384GCC-XML 0.9.0 February 12, 2011 GCC-XML(1)