Generate LLDB C++ from TableGen Files with lldb-tblgen-18

You will turn an LLDB TableGen .td file into generated output, or check that it parses before choosing a backend. The installed manual belongs to LLVM 18's llvm-18 package, version 1:18.1.3-1ubuntu1. On this machine the manpage is present but the lldb-tblgen-18 executable is not, so the commands below are a version-specific workflow based on the local manual. Test them in an LLVM development installation that includes the LLDB tool.

Allow 15 to 30 minutes if you already have a valid TableGen source file and its include directories. You need a shell, an LLDB source tree or another project supplying the required .td files, and permission to write the chosen output directory. Nothing here needs sudo. Do not run a generator as root to solve an ordinary file-permission mistake.

1. Check the tool and input path

Start by confirming the exact executable and the package version on the machine where you will generate code:

$ command -v lldb-tblgen-18
/usr/bin/lldb-tblgen-18
$ lldb-tblgen-18 -version
LLVM version 18.1.3
$ test -r /path/to/input.td && echo 'input is readable'
input is readable

The first two lines are illustrative: the queued Ubuntu package provides the manual, while this reference machine does not provide the executable. Your binary may live under an LLVM installation directory rather than /usr/bin. The input argument is one filename, normally ending in .td. TableGen resolves included files through its built-in search rules and any directories supplied with -I.

2. Parse the file without running a backend

Use -null-backend for a low-risk first pass. It parses the source and builds records, then deliberately does not run a backend:

$ lldb-tblgen-18 -null-backend /path/to/input.td
$ printf 'exit status: %s\n' "$?"
exit status: 0

A zero status means this invocation completed successfully. It is a useful syntax and include-path check, not proof that the input contains the records required by a later LLDB backend. If the command reports an unknown include or record, read the diagnostic before changing anything. Add an include directory explicitly when the source relies on project-relative files:

$ lldb-tblgen-18 -I /path/to/llvm/include -I /path/to/lldb/include \
    -null-backend /path/to/input.td

Use absolute paths while diagnosing. They remove a common distraction: the current working directory changes the meaning of relative include paths.

3. Inspect records before generating code

Once parsing succeeds, print the records to standard output rather than creating a file. This is a read-only inspection step:

$ lldb-tblgen-18 -I /path/to/include -print-records \
    /path/to/input.td > /tmp/lldb-records.txt
$ test -s /tmp/lldb-records.txt && echo 'records were written'
records were written

-print-records is the default backend option. Use -print-detailed-records when you need global variables, classes and records in more detail. These reports are for checking what TableGen built; they are not the C++ implementation that an LLDB build normally consumes.

Keep temporary reports outside the source tree if you are unsure whether a build watches that directory. This avoids triggering unrelated rebuilds and makes it clearer which files are generated deliverables.

4. Emit an output file safely

A project-specific backend option selects what C++ or other output is generated. The local manual lists the common output controls, but the LLDB backend options depend on the source tree and are not enumerated by the short lldb-tblgen page. Ask the installed binary for its complete list, then combine the selected backend with -o:

$ lldb-tblgen-18 --help-list > /tmp/lldb-tblgen-options.txt
$ lldb-tblgen-18 -I /path/to/include -o /path/to/generated/output.cpp \
    -YOUR_LLDB_BACKEND_OPTION /path/to/input.td

Replace -YOUR_LLDB_BACKEND_OPTION with an option shown by your binary. Do not invent a backend name from a nearby LLVM or Clang build. The short manual's documented common options include -o filename, -d filename for a dependency file, -D=macroname for a defined macro, and -write-if-changed to avoid rewriting an unchanged output.

$ mkdir -p /path/to/build/generated
$ lldb-tblgen-18 -I /path/to/include -write-if-changed \
    -o /path/to/build/generated/output.cpp \
    -YOUR_LLDB_BACKEND_OPTION /path/to/input.td
$ test -s /path/to/build/generated/output.cpp && echo 'output is non-empty'
output is non-empty

If the output is wrong, remove only the generated file in the build directory and rerun after correcting the source or backend selection. Do not delete source .td files as a recovery step. If you overwrote a tracked generated file, restore it through your normal version-control workflow, then regenerate into a clean build directory.

5. Produce machine-readable records when needed

For tooling that needs to inspect records, use -dump-json. The option writes a JSON representation of all records, suitable for further automated processing:

$ lldb-tblgen-18 -I /path/to/include -dump-json \
    /path/to/input.td > /tmp/lldb-records.json
$ python3 -m json.tool /tmp/lldb-records.json > /dev/null
$ echo 'valid JSON'
valid JSON

The Python check only validates the captured JSON; it does not validate whether the records are semantically appropriate for LLDB. Keep the output in a temporary or build location until the schema and record names are confirmed.

6. Diagnose slow or surprising runs

Use -time-phases to report parser and backend timing, and -stats for backend statistics:

$ lldb-tblgen-18 -time-phases -stats \
    -YOUR_LLDB_BACKEND_OPTION /path/to/input.td

Debug output from -debug can be much noisier and may expose implementation details that are not stable between LLVM releases. Enable it for a single diagnostic run, capture the output, and turn it off once the failure is understood. A successful exit status still means only that this invocation completed; inspect the generated file and the build's later compiler step.