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
13       Abstract 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
29              · gnu: GNU Compiler Collection C++ (g++)
30
31              · gnu-c: GNU Compiler Collection C (gcc)
32
33              · msvc: Microsoft Visual C++ (cl)
34
35              · msvc-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
80              optional  release  candidate  number, and <id> may contain arbi‐
81              trary 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
106         minor  bug  is  fixed  in  the  XML  output of an existing element or
107         attribute (clients should work unchanged unless  they  want  the  new
108         info).
109
110   With --castxml-gccxml
111       The XML root element tag will be of the form:
112
113          <GCC_XML version="0.9.0" cvs_revision="1.139">
114
115       The version number corresponds to the last gccxml version that was ever
116       released (for backward compatibility).  The cvs_revision  number  is  a
117       running  number  that  is  incremented for each minor change in the xml
118       format.
119

SCHEMA

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

PREPROCESSING

125       CastXML  preprocesses  source  files  using  an internal Clang compiler
126       using its own predefined macros for the  target  platform  by  default.
127       The  --castxml-cc-<id>  option  switches the predefined macros to match
128       those detected from  the  given  compiler  command.   In  either  case,
129       CastXML always adds the following predefined macros:
130
131       __castxml_major__
132              Defined to the CastXML major version number in decimal.
133
134       __castxml_minor__
135              Defined to the CastXML minor version number in decimal.
136
137       __castxml_patch__
138              Defined to the CastXML patch version number in decimal.
139
140       __castxml_check(major,minor,patch)
141              Defined to a constant expression encoding the three version com‐
142              ponents for comparison with __castxml__.  The actual encoding is
143              unspecified.
144
145       __castxml__
146              Defined  to  a  constant expression encoding the CastXML version
147              components:
148
149                 __castxml_check(__castxml_major__,__castxml_minor__,__castxml_patch__)
150
151       __castxml_clang_major__
152              Defined to the  value  of   __clang_major__  from  the  internal
153              Clang.
154
155       __castxml_clang_minor__
156              Defined  to  the  value  of   __clang_minor__  from the internal
157              Clang.
158
159       __castxml_clang_patchlevel__
160              Defined to the value of  __clang_patchlevel__ from the  internal
161              Clang.
162
163       Source  files may use these to identify the tool that is actually doing
164       the preprocessing even when --castxml-cc-<id>  changes  the  predefined
165       macros.
166

FAQ

168   Why are C++ function bodies not dumped in XML?
169       This  feature  has not been implemented because the driving project for
170       which CastXML was written had no need for function bodies.
171
172   Why don't I see templates in the output?
173       This feature has not been implemented because the driving  project  for
174       which  CastXML  was  written  had no need for uninstantiated templates.
175       Template instantiations will still be dumped, though. For example:
176
177          template <class T> struct foo {};
178          typedef foo<int>::foo foo_int;
179
180       will instantiate foo<int>, which will be included in the output.   How‐
181       ever,  there  will  be  no place that explicitly lists the set of types
182       used for the instantiation other than in the name. This is because  the
183       proper  way  to  do  it is to dump the templates too and reference them
184       from the instantiations with the template arguments listed.  Since  the
185       features will be linked they should be implemented together.
186
188       2013-2021 Kitware, Inc.
189
190
191
192
1930.4.3                            Mar 04, 2021                       CASTXML(1)
Impressum