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.0.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

PREPROCESSING

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

FAQ

164   Why are C++ function bodies not dumped in XML?
165       This feature has not been implemented because the driving  project  for
166       which CastXML was written had no need for function bodies.
167
168   Is there a DTD specifying the XML format dumped?
169       No.
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-2019 Kitware, Inc.
188
189
190
191
1920.2.0                            Sep 25, 2019                       CASTXML(1)
Impressum