1CASTXML(1)                          CastXML                         CASTXML(1)
2
3
4

NAME

6       castxml - C-family Abstract Syntax Tree XML Output
7

SYNOPSIS

9          castxml ( <castxml-opt> | <clang-opt> | <src> )...
10

DESCRIPTION

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

OPTIONS

20       The following command-line options are interpreted by castxml.  Remain‐
21       ing options are given to the internal Clang compiler.
22
23       --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
29gnu: GNU Compiler Collection C++ (g++)
30
31gnu-c: GNU Compiler Collection C (gcc)
32
33msvc: Microsoft Visual C++ (cl)
34
35msvc-c: Microsoft Visual C (cl)
36
37              <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
44       --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
49       --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
59       --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
64       -help, --help
65              Print castxml and internal Clang compiler usage information.
66
67       -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
72       --version
73              Print castxml and internal Clang compiler version information.
74
75              Release versions of CastXML use the format:
76
77                 <major>.<minor>.<patch>[-rc<n>][-<id>]
78
79              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
83              Development versions of CastXML use the format:
84
85                 <major>.<minor>.<date>[-<id>]
86
87              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

OUTPUT FORMAT VERSIONS

92   With --castxml-output=<v>
93       The XML root element tag will be of the form:
94
95          <CastXML format="1.2.0">
96
97       • The first component is the epic format version number  given  to  the
98         --castxml-output=<v> flag, and currently must always be 1.
99
100       • 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
104       • 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
109   With --castxml-gccxml
110       The XML root element tag will be of the form:
111
112          <GCC_XML version="0.9.0" cvs_revision="1.139">
113
114       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

SCHEMA

120       XML   Schema   that   describes   both  output  formats  is  available:
121       castxml.xsd.
122

PREPROCESSING

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
130       __castxml_major__
131              Defined to the CastXML major version number in decimal.
132
133       __castxml_minor__
134              Defined to the CastXML minor version number in decimal.
135
136       __castxml_patch__
137              Defined to the CastXML patch version number in decimal.
138
139       __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
144       __castxml__
145              Defined to a constant expression encoding  the  CastXML  version
146              components:
147
148                 __castxml_check(__castxml_major__,__castxml_minor__,__castxml_patch__)
149
150       __castxml_clang_major__
151              Defined  to  the  value  of   __clang_major__  from the internal
152              Clang.
153
154       __castxml_clang_minor__
155              Defined to the  value  of   __clang_minor__  from  the  internal
156              Clang.
157
158       __castxml_clang_patchlevel__
159              Defined  to the value of  __clang_patchlevel__ from the internal
160              Clang.
161
162       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

FAQ

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
171   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
176          template <class T> struct foo {};
177          typedef foo<int>::foo foo_int;
178
179       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-2021 Kitware, Inc.
188
189
190
191
1920.4.3                            May 31, 2021                       CASTXML(1)
Impressum