Building Clang TableGen Sources with clang-tblgen-18

You will check whether clang-tblgen-18 is really installed, parse a Clang TableGen source file without writing generated code, then run a selected Clang backend into a named output file. Allow 15 to 30 minutes if the LLVM source tree is already present. This is a developer tool, not a normal Clang compiler command.

1. Check the executable and package version

The manual describes clang-tblgen as a translator for compiler-related .td files. Its name is easy to confuse with the other TableGen programs shipped by LLVM, and a package can contain the manual without putting this executable on your PATH.

$ command -v clang-tblgen-18
$ dpkg-query -W -f='${Package} ${Version}\n' llvm-18
llvm-18 18.1.3-1ubuntu1
$ clang-tblgen-18 -version

A working installation prints a path and a version line. The final command uses the documented -version option and does not read a source file. If command -v prints nothing, stop here: do not substitute llvm-tblgen-18 for a Clang generator. They share the TableGen machinery but expose different backend options.

On the machine used to prepare this guide, llvm-18 is installed at version 18.1.3, but /usr/bin/clang-tblgen-18 is absent. The installed Clang man page is therefore useful reference material, not proof that the executable is available. Find which package should provide the binary through your normal package-management process before continuing. Do not create a symlink to an unrelated TableGen executable.

2. Locate the source and its include directories

TableGen processes one input file and follows included .td files. Use a source checkout that matches the LLVM and Clang revision you are building. The include directories are passed with -I; the option accepts a full or partial directory path.

$ LLVM_SRC=/path/to/llvm-project/llvm
$ CLANG_SRC=/path/to/llvm-project/clang
$ test -r "$CLANG_SRC/include/clang/Basic/Diagnostic.td" && echo input-readable
input-readable
$ test -d "$LLVM_SRC/include" && test -d "$CLANG_SRC/include" && echo includes-found
includes-found

Replace both placeholder paths with real directories. The source file above is an example of a Clang-owned TableGen input, not a file that the installed binary can invent. If it is missing, check out the matching source package or locate the particular .td file named by your build rather than guessing a nearby file.

3. Parse the source without generating output

Use -null-backend for a first smoke test. It parses the sources and builds the records but does not run a backend, so this step tests paths, includes and TableGen syntax without changing a generated file.

$ clang-tblgen-18 -null-backend \
    -I "$LLVM_SRC/include" \
    -I "$CLANG_SRC/include" \
    "$CLANG_SRC/include/clang/Basic/Diagnostic.td"
$ printf 'exit status: %s\n' "$?"
exit status: 0

There may be no useful standard output on success. The exit status is the checkpoint. A missing include normally points to an incorrect -I directory or a source checkout from a different LLVM revision. Fix the paths first; adding random system include directories can make a mismatched tree appear to work while producing the wrong records.

4. Select a Clang backend and output file

A parse alone does not produce the C++ or other generated artefact. The Clang-specific options in this man page include generators for diagnostics, attributes, declarations, statements and types. Choose the backend required by the build rule you are reproducing. For example, -gen-clang-diags-defs asks for Clang diagnostic definitions.

$ mkdir -p /tmp/clang-tblgen-test
$ clang-tblgen-18 \
    -gen-clang-diags-defs \
    -I "$LLVM_SRC/include" \
    -I "$CLANG_SRC/include" \
    -o /tmp/clang-tblgen-test/DiagnosticDefs.inc \
    "$CLANG_SRC/include/clang/Basic/Diagnostic.td"
$ test -s /tmp/clang-tblgen-test/DiagnosticDefs.inc && echo generated
generated

The output filename is yours to choose. The -o option accepts a filename, while -o - sends generated output to standard output. Treat generated files as build artefacts. Do not point -o at a tracked source file unless the project build explicitly requires that path.

Warning: a normal shell redirection or an existing -o destination can overwrite useful work. Use a temporary output as above, inspect it, then copy or move it into the build directory only when the build instructions say to do so. If this test produced an unwanted file, remove only the known temporary path:

$ rm -- /tmp/clang-tblgen-test/DiagnosticDefs.inc

That removal is irreversible. The source checkout is not changed by the command, and rerunning the generation command recreates the temporary artefact.

5. Make repeatable builds quieter

Use -write-if-changed when a build repeatedly regenerates the same output. The option writes the output file only when it is new or different, which avoids needless timestamp changes. Keep the backend, include paths, input file and output path identical when comparing runs.

$ clang-tblgen-18 \
    -gen-clang-diags-defs \
    -write-if-changed \
    -I "$LLVM_SRC/include" \
    -I "$CLANG_SRC/include" \
    -o /tmp/clang-tblgen-test/DiagnosticDefs.inc \
    "$CLANG_SRC/include/clang/Basic/Diagnostic.td"

For build-system integration, add -d /path/to/dependencies.d to request a dependency filename. The dependency output is separate from the generated C++ file. Do not assume its exact syntax without checking the build system that consumes it.

6. Inspect records and diagnose failures

When you need to see what was parsed rather than a backend's generated file, use -print-records or -print-detailed-records. These write reports to standard output unless you redirect them. For tooling that needs structured data, -dump-json prints a JSON representation of the records.

$ clang-tblgen-18 -dump-json \
    -I "$LLVM_SRC/include" \
    -I "$CLANG_SRC/include" \
    "$CLANG_SRC/include/clang/Basic/Diagnostic.td" \
    > /tmp/clang-tblgen-test/diagnostic-records.json
$ test -s /tmp/clang-tblgen-test/diagnostic-records.json && echo records-captured
records-captured

If parsing fails, read the first diagnostic carefully. A file-not-found error is a path problem. An unknown class or record often means the input and included sources are from different revisions. An unsupported -gen-clang-... option means the executable does not match the Clang source tree or the option was copied from another LLVM release. Confirm the installed binary with -version and compare it with the source checkout before changing flags.