LLVM

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

"LLVM" is an orphan initialism; originally an acronym standing for Low Level Virtual Machine, LLVM today has little to do with virtual machines under the contemporary understanding of the term.

Installation

USE flags

LLVM_TARGETS

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:

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

Finally, rebuild LLVM and Clang:

Emerge

LLVM components

LLVM is comprised of the following components:

• LLVM Core
• BOLT
• Clang
• compiler-rt
• Flang
• libcxx
• libc^{[note 1]}
• 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 and 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 .
• Btop crashes when compiled with libc++ : GitHub issue

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.

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

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

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:

LLVM=1

and

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 do so for fun.

Advanced users can choose to bootstrap LLVM/Clang by building it using the full LLVM toolchain, thus fully dogfooding with clang.

Be warned that due to LLVM's internal structure and style of packaging, this is liable to break across upgrades of major versions.

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 ; otherwise, the two should always produce output with the same ABI.

Preparing the environment

Prepare the environment for the Clang toolchain:

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 which is a drop-in replacement that is significantly faster than the bfd linker.

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

llvm-core/clang-commondefault-compiler-rtdefault-lldllvm-libunwind

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

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:

llvm-core/clangcompiler-clang
llvm-core/llvmcompiler-clang
llvm-runtimes/libcxxcompiler-clang
llvm-runtimes/libcxxabicompiler-clang
llvm-runtimes/compiler-rtcompiler-clang
llvm-runtimes/compiler-rt-sanitizerscompiler-clang
llvm-runtimes/libunwindcompiler-clang
llvm-core/lldcompiler-clang

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

Clang may now be used with other packages!

Bootstrapping Rust

On LLVM-based systems using musl, packages may break if dev-lang/rust-bin is the active Rust installation, and is therefore masked (bug #912154 ). Emerge dev-lang/rust requires a Rust installation, which leads to a circular dependency that cannot be resolved.

In this case Rust can be built in two ways:

• Bootstrapping Rust via (non-LLVM) stage file on the same host
• Bootstrapping Rust via cross compilation from another host via cross compilation

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 by either switching to the LLVM profile, 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++, such libraries must be recompiled 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.

error: cannot open crtbeginS.o: No such file or directory

musl-ld: error: cannot open crtbeginS.o: No such file or directory
musl-ld: error: unable to find library -lgcc
musl-ld: error: unable to find library -lgcc_s
musl-ld: error: unable to find library -lgcc
musl-ld: error: unable to find library -lgcc_s

Bug 951445: emerge --oneshot --nodeps clang-runtime after merging compiler-rt: you should then be able to upgrade libcxxabi without trouble.

Notes

• Compilation