Use llvm-tblgen-18 to Inspect TableGen Records Safely

You will finish with a small, repeatable workflow for parsing a TableGen file with llvm-tblgen-18, inspecting the records it creates, and writing machine-readable output without guessing what the tool did. The examples use the installed Ubuntu package llvm-18, version 18.1.3-1ubuntu1.

Allow about fifteen minutes. You need a shell and permission to read the input file and write the chosen output path. No example needs elevated privileges. This guide uses a disposable file and does not modify LLVM source, system configuration or a build tree.

1. Confirm the installed command

Start by checking the executable and its version. These are ordinary read-only commands:

$ command -v llvm-tblgen-18
/usr/bin/llvm-tblgen-18
$ llvm-tblgen-18 --version
Ubuntu LLVM version 18.1.3
  Optimized build.

The manpage describes llvm-tblgen as a translator for compiler-related target description files, normally files ending in .td. Most LLVM users do not invoke it directly. It is mainly a developer tool for producing parts of a compiler, so use it from the project and revision that owns the input file.

Checkpoint: inspect the options supplied by this installed binary, rather than copying a flag from a different LLVM release:

$ llvm-tblgen-18 --help | sed -n '1,80p'

Useful general options in this build include -I for include directories, -D for a defined macro, -o for the output file, and -d for a dependency file. The action options decide what happens after parsing. --print-records is the default, while --dump-json and --null-backend are useful for inspection and parser-only checks.

2. Create a harmless input file

For a first test, make a tiny TableGen file in a temporary directory. This is ordinary file creation, not an installed-system change:

$ cat > /tmp/tblgen-demo.td <<'EOF'
class Flag<string name> {
  string Name = name;
}

def Verbose : Flag<"verbose">;
EOF

The file declares a parameterised class and one definition that inherits from it. The angle brackets are TableGen syntax. If you place this content in an HTML article or script-generated report, escape those brackets as < and >; the shell example above is meant to be pasted into a terminal.

Checkpoint: verify that the input exists before asking TableGen to process a larger project file:

$ test -r /tmp/tblgen-demo.td && printf '%s\n' 'input is readable'
input is readable

3. Print parsed records to the terminal

Run the file with no action option. The positional filename is the input, and the default action is --print-records:

$ llvm-tblgen-18 /tmp/tblgen-demo.td
------------- Classes -----------------
class Flag<string Flag:name = ?> {
  string Name = Flag:name;
}
------------- Defs -----------------
def Verbose {    // Flag
  string Name = "verbose";
}

This is a useful human check. It shows the class and the resolved definition, so it can reveal a misspelled field, an unexpected superclass or a value that did not resolve as you expected. It is not a stable data interchange format. Do not write a parser that depends on the spacing or the decorative headings.

There is no undo operation here. The command only reads the input and writes to standard output. If the terminal becomes noisy, redirect it to a disposable file or use the JSON mode below.

4. Produce JSON for a repeatable check

Use --dump-json when another tool needs records rather than display text:

$ llvm-tblgen-18 --dump-json /tmp/tblgen-demo.td
{"!instanceof":{"Flag":["Verbose"]},"!tablegen_json_version":1,"Verbose":{"!anonymous":false,"!fields":[],"!name":"Verbose","!superclasses":["Flag"],"Name":"verbose"}}

The JSON includes a TableGen JSON version marker, an inheritance index and the resolved Verbose record. Treat the version marker as part of the format contract: a consumer should check it and fail clearly if it sees a version it does not understand. The exact record set depends on the input and included definitions.

Checkpoint: validate the output with a JSON parser if the result is entering a script:

$ llvm-tblgen-18 --dump-json /tmp/tblgen-demo.td | python3 -m json.tool | sed -n '1,18p'
{
    "!instanceof": {
        "Flag": [
            "Verbose"
        ]
    },
    "!tablegen_json_version": 1,

The parser check is separate from TableGen. A successful JSON parse does not prove that the records are semantically correct for your compiler backend.

5. Choose output deliberately

By default, output goes to standard output. Use -o when a build rule or another command needs a named file:

$ llvm-tblgen-18 --dump-json -o /tmp/tblgen-demo.json /tmp/tblgen-demo.td
$ sed -n '1p' /tmp/tblgen-demo.json
{"!instanceof":{"Flag":["Verbose"]},"!tablegen_json_version":1,"Verbose":{"!anonymous":false,"!fields":[],"!name":"Verbose","!superclasses":["Flag"],"Name":"verbose"}}

--write-if-changed reduces needless rewrites when a generated output is unchanged. It does not make an unsafe output path safe, and it does not compare the generated content with your source file.

6. Separate parsing from backend generation

Use --null-backend when you want to measure or check parsing without producing a backend result:

$ llvm-tblgen-18 --null-backend /tmp/tblgen-demo.td
$ printf 'exit status: %s\n' "$?"
exit status: 0

A zero status means this input passed the invoked TableGen processing path. It does not mean that a target-specific generator will accept the file or that the resulting records are suitable for C++ generation. For real LLVM inputs, use the action required by the owning build rule, such as one of the --gen-* options shown by --help. Do not select a generator merely because its name sounds close to your target.

7. Diagnose the first failure

Keep a non-zero result attached to the input and options that produced it. A missing file is reported plainly and returns status 1:

$ llvm-tblgen-18 /tmp/no-such-input.td
llvm-tblgen-18: Could not open input file '/tmp/no-such-input.td': No such file or directory
$ printf 'exit status: %s\n' "$?"
exit status: 1

For a real project, check the working directory, the input path and every include directory passed with -I before changing the generator. If a file includes another TableGen file, missing include paths can look like a syntax problem. Add the project directories explicitly and keep them in the same order as the project build command.

Do not use sudo to repair an input, include or output-path error. Elevated privileges can hide a permissions mistake and can leave root-owned generated files behind. Fix ownership or permissions in the project directory according to its normal build policy.