Use llvm-config-20 to Build Against the Installed LLVM

llvm-config-20 tells you the include path, library path and linker flags for the LLVM actually sitting on this machine. The commands are read-only and should take about ten minutes, assuming the llvm-20 package is already installed. The guide uses Debian's LLVM 20 package, version 20.1.8, but the option meanings come from the installed manual page.

1. Confirm the command and package

Start by checking which executable will run. Do not assume that an unversioned llvm-config points at the same LLVM release as your compiler or headers.

$ command -v llvm-config-20
/usr/bin/llvm-config-20
$ dpkg-query -W -f='${Package} ${Version}\n' llvm-20
llvm-20 1:20.1.8~++20250804090239+87f0227cb601-1~exp1~20250804210352.139
$ llvm-config-20 --version
20.1.8

Checkpoint: if the package query reports that llvm-20 is not installed, stop here and install it through your normal package-management process. That is the only step in this guide that might need elevated privileges; running llvm-config-20 itself does not need sudo.

2. Inspect the installation paths

Ask the command for paths instead of writing /usr/lib/llvm-20 into a build script. This keeps the script tied to the selected executable.

$ llvm-config-20 --prefix
/usr/lib/llvm-20
$ llvm-config-20 --bindir
/usr/lib/llvm-20/bin
$ llvm-config-20 --includedir
/usr/lib/llvm-20/include
$ llvm-config-20 --libdir
/usr/lib/llvm-20/lib
$ llvm-config-20 --cmakedir
/usr/lib/llvm-20/lib/cmake/llvm

The prefix is not the header directory and it is not the library directory. Use the dedicated option when you need one of those paths. These queries do not change files or environment variables.

3. Capture compiler and linker flags

For a C++ translation unit, --cxxflags supplies the flags needed for LLVM headers. --ldflags supplies the library search flags, while --libs adds the LLVM libraries for named components. Keep the command substitutions adjacent to the compiler invocation so the values come from the same LLVM installation.

$ llvm-config-20 --cxxflags
-I/usr/lib/llvm-20/include -std=c++17   -fno-exceptions -funwind-tables -D_GNU_SOURCE -D__STDC_CONSTANT_MACROS -D__STDC_FORMAT_MACROS -D__STDC_LIMIT_MACROS
$ llvm-config-20 --ldflags
-L/usr/lib/llvm-20/lib
$ llvm-config-20 --libs core support
-lLLVM-20

A representative compile and link command is:

$ c++ $(llvm-config-20 --cxxflags) -c /path/to/program.cpp -o /path/to/program.o
$ c++ /path/to/program.o $(llvm-config-20 --ldflags) $(llvm-config-20 --libs core support) $(llvm-config-20 --system-libs core support) -o /path/to/program

Replace both placeholder paths with your own source and output paths. The example uses ordinary user permissions. It does not install the resulting program or overwrite a system binary.

4. Choose components deliberately

--libs accepts component names after the option. The manual describes all as the default when no component is specified, but asking for the components you use makes the build intent easier to review. The installed command reports the available names in one line:

$ llvm-config-20 --components
aarch64 aarch64asmparser aarch64codegen ... xcoreinfo xray xtensa xtensaasmparser xtensacodegen xtensadesc xtensadisassembler xtensainfo

The output above is shortened for display. To test a component name before putting it in a build file, query it directly:

$ llvm-config-20 --libs core support
-lLLVM-20
$ llvm-config-20 --system-libs core support

An empty --system-libs result is valid here: this installation reports no additional system libraries for these components. Do not copy that assumption to a different component set or LLVM build.

5. Check shared and static linking

This installation reports that the selected components can be linked collectively as shared libraries:

$ llvm-config-20 --shared-mode
shared
$ llvm-config-20 --libnames core support
libLLVM-20.so
$ llvm-config-20 --libfiles core support
/usr/lib/llvm-20/lib/libLLVM-20.so

6. Diagnose mismatched LLVM installations

When a build fails with missing headers or unresolved LLVM symbols, compare the command's identity and paths first:

$ llvm-config-20 --version
20.1.8
$ llvm-config-20 --host-target
x86_64-pc-linux-gnu
$ llvm-config-20 --assertion-mode
OFF
$ llvm-config-20 --has-rtti
YES

The host target describes the target triple used to configure LLVM; it is not a replacement for checking your compiler's target settings. The assertion and RTTI results describe how this copy of LLVM was built, so code that depends on assertions or runtime type information should be checked against these values.

Recovery: if a component query fails, run llvm-config-20 --components and use an exact name from that output. If the command itself is missing, check command -v llvm-config-20 and the llvm-20 package. Do not fix a path mismatch by copying libraries into /usr/lib or changing a system-wide linker configuration; correct the selected LLVM executable or the build configuration instead.

Done means