Check LLVM's Target Library Assumptions Against Shared Libraries

You will finish with a reproducible check that compares LLVM's TargetLibraryInfo, or TLI, with the global function symbols exported by one or more library files. The examples use llvm-tli-checker-18 from Debian package llvm-18, version 1:18.1.3-1ubuntu1.

Allow about fifteen minutes. You need the LLVM 18 checker, a target triple, and library files built for the environment you are checking. The command reads library metadata; it does not modify the libraries, compiler configuration or SDK. No elevated privileges are normally needed.

1. Confirm the installed checker

Check the package and option syntax before building a script around it:

$ command -v llvm-tli-checker-18
/usr/bin/llvm-tli-checker-18
$ dpkg-query -W -f='${Package} ${Version}\n' llvm-18
llvm-18 1:18.1.3-1ubuntu1
$ llvm-tli-checker-18 --help
OVERVIEW: LLVM TargetLibraryInfo versus SDK checker

USAGE: llvm-tli-checker-18 [options] library-file [library-file...]

The installed command accepts library paths after its options. It also accepts -h as an alias for --help. Keep the full command name in scripts: another LLVM version may have different target data or a different installed binary name.

2. Choose the target triple and library files

The --triple value initialises TLI. It must describe the target whose library assumptions you want to test, not merely the machine on which you happen to run the checker. Replace the example with the triple used by your compiler or SDK:

$ llvm-tli-checker-18 \
    --triple=x86_64-pc-linux-gnu \
    --report=summary \
    /usr/lib/x86_64-linux-gnu/libm.so.6

On this installation the command reports 476 symbols known to TLI, of which 430 are available for that triple. It then examines the selected shared object. The exact counts depend on the library build, package updates and target triple.

Use a library file from the SDK or sysroot being checked. Do not infer compatibility from a similarly named host library. A successful read only says that the file could be inspected; it does not prove that the file is suitable for your compiler target.

3. Read the mismatch report

The default report level is discrepancy. For a compact first pass, request summary:

$ llvm-tli-checker-18 --triple=x86_64-pc-linux-gnu \
    --report=summary /usr/lib/x86_64-linux-gnu/libm.so.6
TLI knows 476 symbols, 430 available for 'x86_64-pc-linux-gnu'

Looking for symbols in '/usr/lib/x86_64-linux-gnu/libm.so.6'
Found 1067 global function symbols in '/usr/lib/x86_64-linux-gnu/libm.so.6'
Found a grand total of 1067 library symbols
<< Total TLI yes SDK no:  293
>> Total TLI no  SDK yes: 3
== Total TLI yes SDK yes: 137
FAIL: LLVM TLI doesn't match SDK libraries.

Read the two mismatch directions literally. TLI yes SDK no means TLI believes a function is available but the inspected library does not export it. TLI no SDK yes means the library exports a function that TLI does not mark available. The matching count is shown separately. These are symbol-set comparisons, not runtime tests of calling conventions, ABI details or behaviour.

4. List the symbols that disagree

Omit --report=summary, or say --report=discrepancy, when you need names and demangled descriptions:

$ llvm-tli-checker-18 --triple=x86_64-pc-linux-gnu \
    --report=discrepancy /path/to/libexample.so

Use --report=full only when you need every TLI-known symbol, including matches. Full output is much noisier and is easy to mistake for a list of problems. Start with the summary, then use discrepancy output to identify the definitions or target-library entries that need review.

Do not treat a missing symbol as proof that the library is broken. Check symbol visibility, the intended ABI, the exact SDK version and whether the file is the correct architecture. Conversely, an exported symbol is not automatically safe for LLVM to use: availability can depend on target-specific rules and calling conventions.

5. Check several libraries separately

Passing multiple files normally combines their symbols into one total. Add --separate when you need to see each file's contribution:

$ llvm-tli-checker-18 --triple=x86_64-pc-linux-gnu \
    --separate --report=summary \
    /usr/lib/x86_64-linux-gnu/libm.so.6 \
    /usr/lib/x86_64-linux-gnu/libc.so.6

--separate implies summary reporting unless you override it with another --report value. Separate output helps find a library that contributes no symbols TLI knows about, or a mismatch that is hidden when several libraries are considered together.

If all files share a directory, --libdir prepends that directory to each supplied file name:

$ llvm-tli-checker-18 --triple=x86_64-pc-linux-gnu \
    --libdir=/usr/lib/x86_64-linux-gnu --report=summary libm.so.6

Use explicit paths when reviewing a one-off result. The base-directory option is most useful for repeatable lists or response files.

6. Make a repeatable check with a response file

A response file can hold options and library names. This keeps a long SDK check reviewable and avoids shell quoting mistakes:

$ cat > /tmp/tli-checker.args <<'EOF'
--triple=x86_64-pc-linux-gnu
--report=discrepancy
/path/to/sdk/lib/libc.so.6
/path/to/sdk/lib/libm.so.6
EOF
$ llvm-tli-checker-18 @/tmp/tli-checker.args

The response file is ordinary temporary input. Remove it after checking its contents if it contains paths that should not remain on disk. Do not put secrets in it: this tool has no need for credentials.

7. Handle failures without changing the system

An unrecognised option or no input files produces a non-zero exit status. A missing or unreadable library is also a practical input failure. Check paths and permissions first:

$ test -r /path/to/libexample.so && echo readable
$ file /path/to/libexample.so
$ llvm-tli-checker-18 --help

Do not run the checker as root just to hide a path or permission mistake. Fix the path, grant the least access needed, or run it as the account that owns the SDK checkout. The checker does not install libraries, repair exports or update LLVM's TLI data. Those changes are security- and build-sensitive; make them only through your normal source review and packaging process, with a rollback available.