CASTXML(1)

📦
version 0.8.0 · 17 versions
, in epel 9

🌸 CASTXML(1) — the CastXML glow-up 🌸

okay bestie, welcome to CastXML, the C-family Abstract Syntax Tree XML Output tool 💅 this whole page is your group chat recap of the castxml manual — every flag, every macro, every SEE ALSO-worthy crumb, no cap 🫶

✨ SYNOPSIS ✨

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

that's it, that's the vibe — you throw a mix of castxml options, clang options, and source files at it and it handles it 💖

🦋 DESCRIPTION 🦋

So what does it actually do? It parses C-family source files and, optionally, writes out a subset of the Abstract Syntax Tree (AST) as XML ✨

Your source files get parsed as complete translation units using an internal Clang compiler (yes, Clang is doing the heavy lifting, main character energy fr). XML output only happens if you turn it on with --castxml-output=<v> or --castxml-gccxml — otherwise it's just vibing and parsing 💀

💅 OPTIONS 💅

The following command-line options are interpreted by castxml. Any remaining options get handed straight to the internal Clang compiler, iykyk 🎀

  • --castxml-cc-<id> <cc>, --castxml-cc-<id> ( <cc> <cc-opt>... ) — configures the internal Clang preprocessor and target platform to match the given compiler command. The <id> names a reference compiler that the given command is compatible with, and it must be one of these four, periodt:
    • gnu: GNU Compiler Collection C++ (g++)
    • gnu-c: GNU Compiler Collection C (gcc)
    • msvc: Microsoft Visual C++ (cl)
    • msvc-c: Microsoft Visual C (cl)

<cc> names a compiler (think /usr/bin/gcc or cl) and <cc-opt>... specifies options that may affect its target (like -m32). The target platform detected from that compiler can be overridden by a separate Clang -target option, and the language standard level detected from it can be overridden by a separate Clang -std= option. lowkey flexible ✨

  • --castxml-output=<v> — write XML output to <src>.xml or to the file named by -o. The <v> specifies the "epic" format version number to generate, and it must be 1 🙈
  • --castxml-gccxml — generate XML output in a format close to that of gccxml. Writes output to <src>.xml or the file named by -o. Heads up though: the gccxml format does not support Clang language modes other than -std=c++98 or -std=c89. You can use this output format with language modes -std=c++11, -std=c++14, -std=c99, and -std=c11, but the output won't contain implicit move constructors or move assignment operators, and may contain <Unimplemented/> elements on non-c++98 constructs. not me warning you twice 💀
  • --castxml-start <name>[,<name>]... — start AST traversal at the declaration(s) with the given qualified name(s). You can pass multiple names as a comma-separated list or just repeat the option. your choice, bestie 🎀
  • -help, --help — print castxml and internal Clang compiler usage information.
  • -o <file> — if output is generated (e.g. via --castxml-output=<v>), write it to <file>. At most one <src> file may be specified as input. one source file, one destiny 🦋
  • --version — print castxml and internal Clang compiler version information. and here's the lore on the version strings 👑

Release versions of CastXML use this format:

<major>.<minor>.<patch>[-rc<n>][-<id>]

where the <patch> component is less than 20000000, <n> is an optional release candidate number, and <id> may contain arbitrary text (that's for development between patch versions, iykyk).

Development versions of CastXML use this format:

<major>.<minor>.<date>[-<id>]

where the <date> component is of format CCYYMMDD and <id> may contain arbitrary text. This represents development as of a particular date following the <major>.<minor> feature release ✨

🌈 OUTPUT FORMAT VERSIONS 🌈

⭐ With --castxml-output=<v>

The XML root element tag will be of the form:

<CastXML format="1.4.1">
  • The first component is the epic format version number given to the --castxml-output=<v> flag, and currently must always be 1.
  • The second component is the major format version number and increments when a new XML element is added or for other major changes. Clients will need updating 😭
  • The third component is the minor format version number and increments whenever a new XML attribute is added to an existing element, or a minor bug is fixed in the XML output of an existing element or attribute (clients should work unchanged unless they want the new info 🫶).

⭐ With --castxml-gccxml

The XML root element tag will be of the form:

<GCC_XML version="0.9.0" cvs_revision="1.139">

The version number corresponds to the last gccxml version that was ever released (for backward compatibility, king behavior 👑). The cvs_revision number is a running number that gets incremented for each minor change in the xml format 💫

🧚 SCHEMA 🧚

XML Schema that describes both output formats is available: castxml.xsd. it's giving documentation excellence ✨

🎀 PREPROCESSING 🎀

CastXML preprocesses source files using an internal Clang compiler, and by default it uses its own predefined macros for the target platform. The --castxml-cc-<id> option switches those predefined macros to match the ones detected from the given compiler command. Either way, CastXML always adds the following predefined macros, no exceptions 💅:

  • __castxml_major__ — defined to the CastXML major version number in decimal.
  • __castxml_minor__ — defined to the CastXML minor version number in decimal.
  • __castxml_patch__ — defined to the CastXML patch version number in decimal.
  • __castxml_check(major,minor,patch) — defined to a constant expression encoding the three version components for comparison with __castxml__. The actual encoding is unspecified 🙈
  • __castxml__ — defined to a constant expression encoding the CastXML version components:
__castxml_check(__castxml_major__,__castxml_minor__,__castxml_patch__)
  • __castxml_clang_major__ — defined to the value of __clang_major__ from the internal Clang.
  • __castxml_clang_minor__ — defined to the value of __clang_minor__ from the internal Clang.
  • __castxml_clang_patchlevel__ — defined to the value of __clang_patchlevel__ from the internal Clang.

Source files may use these to identify the tool that is actually doing the preprocessing, even when --castxml-cc-<id> changes the predefined macros. iconic, honestly 💖

🍓 FAQ 🍓

💀 Why are C++ function bodies not dumped in XML?

This feature has not been implemented because the driving project for which CastXML was written had no need for function bodies. that's the whole tea 🫖

💀 Why don't I see templates in the output?

This feature has not been implemented because the driving project for which CastXML was written had no need for uninstantiated templates. Template instantiations will still be dumped, though. For example:

template <class T> struct foo {};
typedef foo<int>::foo foo_int;

will instantiate foo<int>, which will be included in the output ✨ However, there will be no place that explicitly lists the set of types used for the instantiation other than in the name. Why? Because the proper way to do it is to dump the templates too and reference them from the instantiations with the template arguments listed. Since the features will be linked, they should be implemented together. teamwork makes the dream work fr fr 🫶

2013-2026 Kitware, Inc.

and that's the whole manual, bestie 💜 no notes, no skips, every single detail accounted for 🎀

cute little sign-off: this page is from CastXML version 0.8.0, dated Sep 27, 2026 — go forth and dump some ASTs, you absolute icon 🌈✨💅

📦 where this page comes from