Dumping ASTs and LLVM IR

When debugging a compiler problem, it may be necessary to dump the AST produced by clang. It can be slightly tricky to dump the AST for real programs because of the way that clang exposes the functionality for dumping ASTs. This page explains why and how to dump the AST for real programs.

Clang has model often used in compilers where a compiler driver invokes a series of tools to compile a program. Each tool does a specific thing. One tool may be a compiler front-end, while another tool may invoke the linker. Clang provides a GCC-compatible driver. There is functionality available in the front-end that is not exposed by the GCC-compatible driver, which is available when the compiler driver is in the -cc1 mode. The -cc1 mode runs the front-end only, not the clang driver. It is entered by passing the -cc1 flag to clang:

clang -cc1 ...

The tricky part about using the -cc1 mode is that the compiler driver actually does a bunch of hidden work on behalf of users when compiling programs. This includes figuring out where to look for include files (the include path), as well as setting flags that control standard defines and language options. If you just add -cc1 to your compiler command line, the compiler is likely to fail or compile the program with the wrong settings.

Dumping the AST is functionality that is exposed when the driver is in -cc1 mode, via the -ast-dump flag. When you most need to dump the AST (a real program that is failing), adding -cc1 -ast-dump is likely to not work. clang has a way around this: the -### option, which causes the driver to dump the list of tools commands that it would invoke on your behalf.

So to dump your AST for a real program:

1. Get the command line used to compile the real program. This can be obtained from your build system in a build-system specific way. Most build systems let you log the set of build commands that would be executed, dumping the commands to standard output or a file.
2. Try to narrow the compiler command line down to the specific compiland in question (for example, just compile the file or files that contain the functions in question). You will be happy to not have to wade through the extra information.
3. Invoke the compiler command line, adding -### to it and dumping the output to another log file. Depending on your shell, you may need to quote it: '-###'.
4. Find the actual clang command and copy it to a separate script file (yes, you can just cut-and-paste the command and edit it, but the command-line is usually long enough that you'll save time and avoid errors by just creating script).
5. The actual clang command will already include -cc1'. Just add -ast-dump to the command-line in the script.