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