LLVM

Resources

Project

Home

Official documentation

Package information

GitHub

Wikipedia

#llvm (on irc://irc.oftc.net)

The LLVM Project is a collection of modular and reusable compiler and toolchain technologies.

"LLVM" is not an acronym, but the literal name of the project. Despite the original meaning of the now abandoned acronym ("Low Level Virtual Machine"), LLVM has little to do with virtual machines in the usual meaning of the term.

Installation

USE flags

USE flags for llvm-core/llvm Low Level Virtual Machine

+binutils-plugin	Build the binutils plugin
+debug	Enable extra debug codepaths, like asserts and extra output. If you want to get meaningful backtraces see https://wiki.gentoo.org/wiki/Project:Quality_Assurance/Backtraces
+libffi	Enable support for Foreign Function Interface library
debuginfod	Install llvm-debuginfod (requires net-misc/curl and dev-cpp/cpp-httplib)
doc	Build and install the HTML documentation and regenerate the man pages
exegesis	Enable performance counter support for llvm-exegesis tool that can be used to measure host machine instruction characteristics
libedit	Use the libedit library (replacement for readline)
ncurses	Support querying terminal properties using ncurses' terminfo
test	Enable dependencies and/or preparations necessary to run tests (usually controlled by FEATURES=test but can be toggled independently)
verify-sig	Verify upstream signatures on distfiles
xar	Support dumping LLVM bitcode sections in Mach-O files (uses app-arch/xar)
xml	Add support for XML files
z3	Enable support for sci-mathematics/z3 constraint solver
zstd	Enable support for ZSTD compression

Data provided by the Gentoo Package Database · Last update: 2025-06-15 02:18 More information about USE flags

LLVM_TARGETS

Warning
Overriding LLVM_TARGETS is not recommend, one should only set these if the inherit risks are fully understood. For further information, refer to this forum post.

In this example, LLVM_TARGET_AArch64 will be removed from LLVM_TARGETS. In /etc/portage/profile/package.use.mask, create a file with the following contents:

FILE /etc/portage/profile/package.use.mask/llvm_targets

llvm-core/llvm LLVM_TARGETS: AArch64
llvm-core/clang LLVM_TARGETS: AArch64

Finally, rebuild LLVM and Clang:

root #emerge --ask --oneshot llvm-core/llvm llvm-core/clang

Emerge

root #emerge --ask llvm-core/llvm

LLVM components

LLVM is comprised of the following components:

• LLVM Core
• BOLT
• Clang
• compiler-rt
• libcxx
• libc
• libclc
• LLD
• LLDB
• MLIR
• OpenMP
• polly

Advanced Usage

LLVM profiles

The LLVM profiles in Gentoo are experimental and intended for playing around with pure-LLVM systems (no GCC).

Most people do not want these even if choosing to use Clang to build most packages.

They come with no guarantees of support or stability. They are not simply the same as setting CC and CXX for Clang. The LLVM profiles use libcxx which means they're ABI-incompatible with the regular profiles using libstdc++.

See also the following bugs:

• LLVM profiles: rename libcxx-using profiles to include libcxx in the name - bug #944478
• LLVM profiles: add separate libstdc++ profiles - bug #944482
• LLVM profile links should have a warning above them - bug #944483.

Desktop LLVM profiles

Desktop profiles for LLVM can be created by following Combining multiple profiles from the Gentoo ebuild repository at one's own risk.

Using libcxx

Using libcxx / libc++ breaks ABI. Doing so means that GCC cannot be used as a fallback. See the LLVM profile section for more.

Kernel

The Linux kernel can be compiled with Clang and the LLVM toolchain by defining a kernel environment variable.

root #LLVM=1

To configure Clang specific kernel options such as link-time optimizations or control flow integrity, run the following command:

root #LLVM=1 make menuconfig

The above example demonstrates using menuconfig. Other options are nconfig and xconfig. Next, compile the kernel as normal.

root #LLVM=1 make -j$N

In the past, it was necessary to pass LLVM_IAS=1 to use the Clang internal assembler for a complete LLVM toolchain built kernel. This is no longer required since LLVM=1 now defaults to include the Clang internal assembler. Use LLVM_IAS=0 to disable the internal assembler if desired, otherwise stick to the default behavior.

Distribution Kernel

Compile the distribution kernels (for clarity's sake, not including the binary kernel) with LLVM using the following configs in addition to the values in package.env or make.conf as described in LLVM/Clang:

FILE /etc/portage/env/llvm-kernel

LLVM=1

and

FILE /etc/portage/package.env/gentoo-kernel

sys-kernel/gentoo-kernel llvm-kernel

Bootstrapping the LLVM toolchain

For a "pure" Clang toolchain, one can build the whole LLVM stack using itself. This is unnecessary but users may choose to do it for fun.

Advanced users may optionally choose to bootstrap LLVM/Clang by building it using the full LLVM toolchain.

This is required only if looking to move a system to be entirely GCC-free (which is currently not possible on Glibc systems). This is not yet supported and is dangerous.

Mixing Clang and GCC should be fine, unless using default-libcxx or default-compiler-rt. Clang and GCC should otherwise always produce output with the same ABI.

For purity, however, some may wish to build Clang and the rest of the LLVM toolchain with itself, to prove it works and to fully dogfood using Clang.

Be warned that because of a combination of how LLVM is packaged and LLVM's internal structure, this is liable to break across upgrades of major versions.

Preparing the environment

Prepare the environment for the Clang toolchain:

FILE /etc/portage/env/compiler-clang

COMMON_FLAGS="-march=native -O2 -pipe"
CFLAGS="${COMMON_FLAGS}"
CXXFLAGS="${COMMON_FLAGS}"

CC="clang"
CXX="clang++"

LDFLAGS="-fuse-ld=lld -rtlib=compiler-rt -unwindlib=libunwind -Wl,--as-needed"

This example replaces not only the compiler but also the GNU linker ld.bfd with the LLVM linker lld. It is a drop-in replacement, but significantly faster than the bfd linker.

Set USE flags default-compiler-rt default-lld llvm-libunwind for Clang via /etc/portage/package.use:

FILE /etc/portage/package.use/clang

llvm-core/clang-common default-compiler-rt default-lld llvm-libunwind

Then install Clang, LLVM, compiler-rt, llvm-runtimes/libunwind, and lld with the default GCC environment:

root #emerge llvm-core/clang llvm-core/llvm llvm-runtimes/compiler-rt llvm-runtimes/libunwind llvm-core/lld

It is also possible to add the default-libcxx USE flag to use LLVM's C++ STL with clang, however this is heavily discouraged because libstdc++ and libc++ are not ABI compatible. i.e. A program built against libstdc++ will likely break when using a library built against libc++, and vice versa.

Note that llvm-runtimes/libunwind deals with linking issues that sys-libs/libunwind has, so it is preferred to use and replace the non-llvm libunwind package if installed (it builds with -lgcc_s to resolve issues with __register_frame / __deregister_frame undefined symbols).

Finalizing

Enable the Clang environment for these packages now:

FILE /etc/portage/package.env

llvm-core/clang compiler-clang
llvm-core/llvm compiler-clang
llvm-runtimes/libcxx compiler-clang
llvm-runtimes/libcxxabi compiler-clang
llvm-runtimes/compiler-rt compiler-clang
llvm-runtimes/compiler-rt-sanitizers compiler-clang
llvm-runtimes/libunwind compiler-clang
llvm-core/lld compiler-clang

Repeat the emerge step with the new environment - the toolchain will now be rebuilt with itself instead of GCC:

root #emerge llvm-core/clang llvm-core/llvm llvm-runtimes/libcxx llvm-runtimes/libcxxabi llvm-runtimes/compiler-rt llvm-runtimes/compiler-rt-sanitizers llvm-runtimes/libunwind llvm-core/lld

Clang may now be used with other packages!

Troubleshooting

ld.lld: error: undefined symbol: ... std::__1::basic_string

This means that libc++ has been enabled instead of libstdc++ as the default C++ standard library for Clang either by switching to the LLVM profile, or by installing llvm-core/clang-common with USE=default-libcxx or by adding --stdlib=libc++ directly in CXXFLAGS. Switching to libc++ breaks ABI compatibility for libraries with a C++ public interface (for example, libLLVM), because libc++ uses the std::__1 namespace. To use libc++, it is necessary to recompile such libraries with emerge -av1 llvm-core/llvm && emerge @preserved-rebuild before installing other software.

Compiling with GCC on LLVM profile

/usr/src/debug/sys-libs/glibc-2.37-r3/glibc-2.37/csu/../sysdeps/x86_64/start.S:103: undefined reference to `main'

Use bfd linker. Add -fuse-ld=bfd to CFLAGS, CXXFLAGS and LDFLAGS at the /etc/portage/env/compiler-gcc-lto or /etc/portage/env/compiler-gcc configuration files .