1.. castxml-manual-description: C-family Abstract Syntax Tree XML Output
2
3castxml(1)
4**********
5
6Synopsis
7========
8
9::
10
11  castxml ( <castxml-opt> | <clang-opt> | <src> )...
12
13Description
14===========
15
16Parse C-family source files and optionally write a subset of the
17Abstract Syntax Tree (AST) to a representation in XML.
18
19Source files are parsed as complete translation units using an
20internal `Clang`_ compiler.  XML output is enabled by the
21``--castxml-output=<v>`` or ``--castxml-gccxml`` option.
22
23.. _`Clang`: http://clang.llvm.org/
24.. _`gccxml`: http://gccxml.org
25
26Options
27=======
28
29The following command-line options are interpreted by ``castxml``.
30Remaining options are given to the internal Clang compiler.
31
32``--castxml-cc-<id> <cc>``, ``--castxml-cc-<id> "(" <cc> <cc-opt>... ")"``
33  Configure the internal Clang preprocessor and target platform to
34  match that of the given compiler command.  The ``<id>`` names
35  a reference compiler with which the given command is compatible.
36  It must be one of:
37
38  * ``gnu``: GNU Compiler Collection C++ (g++)
39  * ``gnu-c``: GNU Compiler Collection C (gcc)
40  * ``msvc``: Microsoft Visual C++ (cl)
41  * ``msvc-c``: Microsoft Visual C (cl)
42
43  ``<cc>`` names a compiler (e.g. ``/usr/bin/gcc`` or ``cl``) and
44  ``<cc-opt>...`` specifies options that may affect its target
45  (e.g. ``-m32``).
46  The target platform detected from the given compiler may be
47  overridden by a separate Clang ``-target`` option.
48  The language standard level detected from the given compiler
49  may be overridden by a separate Clang ``-std=`` option.
50
51``--castxml-output=<v>``
52  Write XML output to to ``<src>.xml`` or file named by ``-o``.
53  The ``<v>`` specifies the "epic" format version number to generate,
54  and must be ``1``.
55
56``--castxml-gccxml``
57  Generate XML output in a format close to that of `gccxml`_.
58  Write output to ``<src>.xml`` or file named by ``-o``.
59  The gccxml format does not support Clang language modes other than
60  ``-std=c++98`` or ``-std=c89``.  This output format may be used with
61  language modes ``-std=c++11``, ``-std=c++14``, ``-std=c99``, and
62  ``-std=c11`` but the output will not contain implicit move constructors
63  or move assignment operators, and may contain ``<Unimplemented/>``
64  elements on non-c++98 constructs.
65
66``--castxml-start <name>[,<name>]...``
67  Start AST traversal at declaration(s) with the given qualified name(s).
68  Multiple names may be specified as a comma-separated list or by repeating
69  the option.
70
71``-help``, ``--help``
72  Print ``castxml`` and internal Clang compiler usage information.
73
74``-o <file>``
75  If output is generated (e.g. via ``--castxml-output=<v>``), write
76  the output to ``<file>``.  At most one ``<src>`` file may be specified
77  as input.
78
79``--version``
80  Print ``castxml`` and internal Clang compiler version information.
81
82
83Output Format Versions
84======================
85
86With ``--castxml-output=<v>``
87-----------------------------
88
89The XML root element tag will be of the form:
90
91.. code-block:: xml
92
93  <CastXML format="1.0.0">
94
95* The first component is the ``epic`` format version number given to the
96  ``--castxml-output=<v>`` flag, and currently must always be ``1``.
97* The second component is the ``major`` format version number and increments
98  when a new XML element is added or for other major changes.
99  Clients will need updating.
100* The third component is the ``minor`` format version number and increments
101  whenever a new XML attribute is added to an existing element or a minor
102  bug is fixed in the XML output of an existing element or attribute
103  (clients should work unchanged unless they want the new info).
104
105With ``--castxml-gccxml``
106-------------------------
107
108The XML root element tag will be of the form:
109
110.. code-block:: xml
111
112  <GCC_XML version="0.9.0" cvs_revision="1.139">
113
114The ``version`` number corresponds to the last `gccxml`_ version that was
115ever released (for backward compatibility).  The ``cvs_revision`` number is
116a running number that is incremented for each minor change in the xml format.
117
118
119Preprocessing
120=============
121
122CastXML preprocesses source files using an internal Clang compiler
123using its own predefined macros for the target platform by default.
124The ``--castxml-cc-<id>`` option switches the predefined macros
125to match those detected from the given compiler command.  In either
126case, CastXML always adds the following predefined macros:
127
128``__castxml__``
129  Defined to an integer encoding the CastXML version number as
130  ``printf("%d%03d%03d",major,minor,patch)``.
131
132``__castxml_clang_major__``
133  Defined to the value of  ``__clang_major__`` from the internal Clang.
134
135``__castxml_clang_minor__``
136  Defined to the value of  ``__clang_minor__`` from the internal Clang.
137
138``__castxml_clang_patchlevel__``
139  Defined to the value of  ``__clang_patchlevel__`` from the internal Clang.
140
141Source files may use these to identify the tool that is actually doing the
142preprocessing even when ``--castxml-cc-<id>`` changes the predefined macros.
143
144FAQ
145===
146
147Why are C++ function bodies not dumped in XML?
148----------------------------------------------
149
150This feature has not been implemented because the driving project for which
151CastXML was written had no need for function bodies.
152
153Is there a DTD specifying the XML format dumped?
154------------------------------------------------
155
156No.
157
158Why don't I see templates in the output?
159----------------------------------------
160
161This feature has not been implemented because the driving project for which
162CastXML was written had no need for uninstantiated templates.
163Template instantiations will still be dumped, though. For example:
164
165.. code-block:: c++
166
167  template <class T> struct foo {};
168  typedef foo<int>::foo foo_int;
169
170will instantiate ``foo<int>``, which will be included in the output.
171However, there will be no place that explicitly lists the set of types used
172for the instantiation other than in the name. This is because the proper way to
173do it is to dump the templates too and reference them from the instantiations
174with the template arguments listed. Since the features will be linked they
175should be implemented together.
176