Use clang-tblgen-20 to Inspect Clang TableGen Inputs

You will finish with a repeatable way to feed a small .td file to clang-tblgen-20, inspect the records it sees, and request machine-readable JSON. The examples use Ubuntu LLVM 20.1.8 from the installed llvm-20 package.

Allow about fifteen minutes. You need a shell, the clang-tblgen-20 executable, and a text editor or a way to create a temporary file. The examples only read a temporary input and write output under /tmp. They do not install anything, alter Clang, or write to a source tree.

1. Confirm the installed tool

Start with read-only checks. They do not need elevated privileges:

$ command -v clang-tblgen-20
/usr/bin/clang-tblgen-20
$ clang-tblgen-20 --version
Ubuntu LLVM version 20.1.8
  Optimized build.
$ dpkg-query -W -f='${Package} ${Version}\n' llvm-20
llvm-20 1:20.1.8-1~exp1

The package revision can differ on another machine. The useful distinction is between the program's LLVM version and the distribution's package revision. If command -v finds nothing, stop here and install or enable the package through your normal system-management process. Do not work around a missing executable by guessing a path.

2. Create a minimal TableGen input

clang-tblgen-20 translates compiler-related TableGen description files. Its input is normally a filename ending in .td; the filename is positional. Create a harmless scratch file:

$ workdir=$(mktemp -d /tmp/clang-tblgen-20.XXXXXX)
$ printf '%s\n' 'class Demo { int Value = 1; }' > "$workdir/demo.td"
$ sed -n '1p' "$workdir/demo.td"
class Demo { int Value = 1; }

This declares a class named Demo with one integer field. It does not define an instance, so the default record listing will show a class but no defs. In a real Clang source checkout, the input may include other .td files and use include directories. Keep this first test self-contained so that a missing include cannot be confused with a problem in the executable.

The temporary directory is not a persistent configuration change. Leave it in place while working through the later examples. If you need to keep the input, copy it to a deliberate project location after reviewing it. Otherwise remove this particular temporary directory and its files in step 7.

3. Print the records

Run the input without an action option. The installed program defaults to --print-records:

$ clang-tblgen-20 "$workdir/demo.td"
------------- Classes -----------------
class Demo {
  int Value = 1;
}
------------- Defs -----------------

The headings separate classes from defs. An empty defs section is expected here because the sample declares a class only. A real input can produce many records, and the exact ordering and formatting are output details rather than a stable API for scripts.

You can make the default explicit when reading a longer command:

$ clang-tblgen-20 --print-records "$workdir/demo.td" > "$workdir/records.txt"
$ sed -n '1,12p' "$workdir/records.txt"

Use ordinary shell redirection when you want to save stdout. Do not expect -o to be implied by redirection: -o is a TableGen option for selecting an output file, and some output actions require it.

4. Emit JSON for inspection or tooling

Select --dump-json when another program needs a machine-readable representation:

$ clang-tblgen-20 --dump-json "$workdir/demo.td" > "$workdir/demo.json"
$ sed -n '1p' "$workdir/demo.json"
{"!instanceof":{"Demo":[]},"!tablegen_json_version":1}

The JSON includes a TableGen JSON version marker and an !instanceof index. The exact record set depends on the input. Treat the output as data generated by this LLVM tool version, not as a promise that every future release will format or order fields identically.

Check that the file is valid JSON with a tool already present on your system:

$ python3 -m json.tool "$workdir/demo.json" > /dev/null
$ printf 'JSON check: %s\n' "$?"
JSON check: 0

If Python is not available, inspect the command's exit status instead. A non-zero status from clang-tblgen-20 means its output is not a successful result, even if a partial file was created.

5. Add include paths only when the input needs them

The -I option adds a directory searched for included TableGen files. Keep the input and include directory separate, and quote paths that may contain spaces:

$ clang-tblgen-20 -I "$workdir/includes" "$workdir/demo.td"

The command above fails if the directory or an included file is absent. That is useful: it tells you the dependency is not available. Do not create arbitrary include files just to silence an error, because the definitions they provide affect generated output.

-D defines a macro name for the TableGen preprocessor, while -I supplies an include directory. These options affect how an input is interpreted; record the exact values in your build command if you need reproducible output.

6. Diagnose the two common command errors

A missing input is a file or path problem. Reproduce it without privileges:

$ clang-tblgen-20 "$workdir/missing.td"
clang-tblgen-20: Could not open input file '.../missing.td': No such file or directory
$ printf 'exit status: %s\n' "$?"
exit status: 1

The temporary-directory portion of the diagnostic varies. Check pwd, the filename, and the result of ls -l "$workdir". sudo will not fix a misspelt path.

Some actions need an explicit output file. For example, the dependency option -d must be used together with -o:

$ clang-tblgen-20 -d "$workdir/demo.d" "$workdir/demo.td"
clang-tblgen-20: the option -d must be used together with -o
$ printf 'exit status: %s\n' "$?"
exit status: 1

This is an option-contract error, not a permissions problem. Do not add elevated privileges. Before using a generator option in a build, check its help text and provide the output path the option requires. Also remember that a generator action can overwrite an existing output file, so review the path before running it against a source tree.

7. Clean up and verify the result

When the inspection is complete, check what the scratch directory contains:

$ find "$workdir" -maxdepth 1 -type f -printf '%f\n' | sort
demo.json
demo.td
records.txt

Remove only the directory you created if you no longer need those files:

$ rm -rf -- "$workdir"
$ test ! -e "$workdir" && echo 'scratch directory removed'
scratch directory removed

There is no undo for a generated file you deliberately removed, so save any output you need before this step. The commands in this guide do not change a service, compiler installation, build configuration or system-wide state.