User:Csfore/LLVM

The LLVM Project is a collection of modular and reusable compiler and toolchain technologies. Despite its name, LLVM has little to do with traditional virtual machines.

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-01-11 18:11 More information about USE flags

LLVM_TARGETS

TODO

Emerge

root #emerge --ask llvm-core/llvm

LLVM components

LLVM is comprised of the following components:

LLVM Core
Clang
LLDB
libcxx
libc^{[note 1]}
compiler-rt
MLIR
OpenMP
polly
libclc
LLD
BOLT

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++.

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:

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

sys-devel/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 .

Notes

↑ Not supported by Gentoo, as of 2025-01-06

[not-supported-1] Not supported by Gentoo, as of 2025-01-06

[note 1]