1CASTXML(1) CastXML CASTXML(1)
2
6 castxml - C-family Abstract Syntax Tree XML Output
7
9 castxml ( <castxml-opt> | <clang-opt> | <src> )...
10
12 Parse C-family source files and optionally write a subset of the Ab‐
13 stract Syntax Tree (AST) to a representation in XML.
14 Source files are parsed as complete translation units using an internal
16 Clang compiler. XML output is enabled by the --castxml-output=<v> or
17 --castxml-gccxml option.
18
20 The following command-line options are interpreted by castxml. Remain‐
21 ing options are given to the internal Clang compiler.
22 --castxml-cc-<id> <cc>, --castxml-cc-<id> "(" <cc> <cc-opt>... ")"
24 Configure the internal Clang preprocessor and target platform to
25 match that of the given compiler command. The <id> names a ref‐
26 erence compiler with which the given command is compatible. It
27 must be one of:
28 • gnu: GNU Compiler Collection C++ (g++)
30 • gnu-c: GNU Compiler Collection C (gcc)
32 • msvc: Microsoft Visual C++ (cl)
34 • msvc-c: Microsoft Visual C (cl)
36 <cc> names a compiler (e.g. /usr/bin/gcc or cl) and <cc-opt>...
38 specifies options that may affect its target (e.g. -m32). The
39 target platform detected from the given compiler may be overrid‐
40 den by a separate Clang -target option. The language standard
41 level detected from the given compiler may be overridden by a
42 separate Clang -std= option.
43 --castxml-output=<v>
45 Write XML output to to <src>.xml or file named by -o. The <v>
46 specifies the "epic" format version number to generate, and must
47 be 1.
48 --castxml-gccxml
50 Generate XML output in a format close to that of gccxml. Write
51 output to <src>.xml or file named by -o. The gccxml format does
52 not support Clang language modes other than -std=c++98 or
53 -std=c89. This output format may be used with language modes
54 -std=c++11, -std=c++14, -std=c99, and -std=c11 but the output
55 will not contain implicit move constructors or move assignment
56 operators, and may contain <Unimplemented/> elements on
57 non-c++98 constructs.
58 --castxml-start <name>[,<name>]...
60 Start AST traversal at declaration(s) with the given qualified
61 name(s). Multiple names may be specified as a comma-separated
62 list or by repeating the option.
63 -help, --help
65 Print castxml and internal Clang compiler usage information.
66 -o <file>
68 If output is generated (e.g. via --castxml-output=<v>), write
69 the output to <file>. At most one <src> file may be specified
70 as input.
71 --version
73 Print castxml and internal Clang compiler version information.
74 Release versions of CastXML use the format:
76 <major>.<minor>.<patch>[-rc<n>][-<id>]
78 where the <patch> component is less than 20000000, <n> is an op‐
80 tional release candidate number, and <id> may contain arbitrary
81 text (in case of development between patch versions).
82 Development versions of CastXML use the format:
84 <major>.<minor>.<date>[-<id>]
86 where the <date> component is of format CCYYMMDD and <id> may
88 contain arbitrary text. This represents development as of a
89 particular date following the <major>.<minor> feature release.
90
92 With --castxml-output=<v>
93 The XML root element tag will be of the form:
94 <CastXML format="1.4.0">
96 • The first component is the epic format version number given to the
98 --castxml-output=<v> flag, and currently must always be 1.
99 • The second component is the major format version number and incre‐
101 ments when a new XML element is added or for other major changes.
102 Clients will need updating.
103 • The third component is the minor format version number and increments
105 whenever a new XML attribute is added to an existing element or a mi‐
106 nor bug is fixed in the XML output of an existing element or attri‐
107 bute (clients should work unchanged unless they want the new info).
108 With --castxml-gccxml
110 The XML root element tag will be of the form:
111 <GCC_XML version="0.9.0" cvs_revision="1.139">
113 The version number corresponds to the last gccxml version that was ever
115 released (for backward compatibility). The cvs_revision number is a
116 running number that is incremented for each minor change in the xml
117 format.
118
120 XML Schema that describes both output formats is available:
121 castxml.xsd.
122
124 CastXML preprocesses source files using an internal Clang compiler us‐
125 ing its own predefined macros for the target platform by default. The
126 --castxml-cc-<id> option switches the predefined macros to match those
127 detected from the given compiler command. In either case, CastXML al‐
128 ways adds the following predefined macros:
129 __castxml_major__
131 Defined to the CastXML major version number in decimal.
132 __castxml_minor__
134 Defined to the CastXML minor version number in decimal.
135 __castxml_patch__
137 Defined to the CastXML patch version number in decimal.
138 __castxml_check(major,minor,patch)
140 Defined to a constant expression encoding the three version com‐
141 ponents for comparison with __castxml__. The actual encoding is
142 unspecified.
143 __castxml__
145 Defined to a constant expression encoding the CastXML version
146 components:
147 __castxml_check(__castxml_major__,__castxml_minor__,__castxml_patch__)
149 __castxml_clang_major__
151 Defined to the value of __clang_major__ from the internal
152 Clang.
153 __castxml_clang_minor__
155 Defined to the value of __clang_minor__ from the internal
156 Clang.
157 __castxml_clang_patchlevel__
159 Defined to the value of __clang_patchlevel__ from the internal
160 Clang.
161 Source files may use these to identify the tool that is actually doing
163 the preprocessing even when --castxml-cc-<id> changes the predefined
164 macros.
165
167 Why are C++ function bodies not dumped in XML?
168 This feature has not been implemented because the driving project for
169 which CastXML was written had no need for function bodies.
170 Why don't I see templates in the output?
172 This feature has not been implemented because the driving project for
173 which CastXML was written had no need for uninstantiated templates.
174 Template instantiations will still be dumped, though. For example:
175 template <class T> struct foo {};
177 typedef foo<int>::foo foo_int;
178 will instantiate foo<int>, which will be included in the output. How‐
180 ever, there will be no place that explicitly lists the set of types
181 used for the instantiation other than in the name. This is because the
182 proper way to do it is to dump the templates too and reference them
183 from the instantiations with the template arguments listed. Since the
184 features will be linked they should be implemented together.
185
187 2013-2023 Kitware, Inc.
1880.6.2 Sep 20, 2023 CASTXML(1)