DeveloperWiki:Toolchain maintenance

From ArchWiki

This page is intended to contain all relevant information to bootstrap the toolchain on Arch Linux, including any issues that are expected to be found, as well as providing documentation on the build order when new versions of important toolchain packages are released.

Build Order

For major version updated (i.e. anything other than a point release), the toolchain should be completely bootstrapped to ensure version matches across components and reproducibility. The toolchain build order is as follows:

linux-api-headers -> glibc -> binutils -> gcc -> glibc -> binutils -> gcc

This build order essentially consists of the startpoint linux-api-headers and two times the sequence

glibc -> binutils -> gcc
  • linux-api-headers: Provides sanitized kernel headers needed to issue syscalls
  • glibc: Abstracts syscalls with linux-api-headers and makes it easily available to the userspace
  • binutils: Links against glibc and provides low level tools such as "as" (GNU assembler)
  • gcc: Requires tools from binutils and links against glibc

The headers are required to build glibc but don't interact with binutils or gcc. The first glibc build is done with an old binutils and gcc version. Going through the build sequence the amount of old tools lowers until gcc can be build with the new glibc and binutils version.

The second sequence of glibc -> binutils -> gcc is then required to build the toolchain itself with the new gcc. gcc is not necesserily needed here as it's the last item in the first sequence which therefore is build with all new tools already available. Though there has been an reproducibility issue, so building gcc a second time is encouraged.

Note that these builds need to be done "manually" using makechrootpkg as we want to install the build package at each step (and not clean the build root between packages). Pkgrel for the packages should be bumped to their intended final version at the beginning of this process.

Anything besides minor patch level updates (e.g. glibc-2.31 -> glibc-2.31.1), or patching individual bugs, generally do not require a full toolchain rebuild. Version bumps might trigger a full rebuild, regardless of soname bumps (e.g glibc-2.31 -> glibc-2.32).

Linux Api Headers

The linux-api-headers package, provides linux kernel headers that have been sanitised for use in userspace. Note, these are distinct from the linux-headers packages provided along size linux and do not need to be kept version synced with the running kernel. The usual practice is to only do a major version bump when updating another toolchain component, as major updates are rarely in demand.

Sources are signed by either Linus Torvalds (0xABAF11C65A2970B130ABE3C479BE3E4300411886) or Greg Kroah-Hartman (0x647F28654894E3BD457199BE38DBBDC86092693E), and sha256 sums are provided in a signed file in the source tarball directory

linux-api-headers makedepends

The only makedependency of linux-api-headers is rsync. It's required by the kernel Makefile which uses rsync to recursively copy over header files to a new location. Line 1268 of the root Makefile of kernel 5.17.6:

mkdir -p $(INSTALL_HDR_PATH); \
rsync -mrl --include='*/' --include='*\.h' --exclude='*' \
usr/include $(INSTALL_HDR_PATH)
  • TODO: document using libdrm headers.

GNU C Library

Provided by glibc.

Second step of the toolchain, also, it needs to be rebuilt after a new gcc rebuild.

There are some packages that require a rebuild after a new glibc, regardless of a so bump, such as valgrind.

GNU Binutils

See DeveloperWiki:Toolchain maintenance/Binutils

GNU Compiler Collection

Provided by gcc.

Last (or first) step of the toolchain, and vital to building its entirety. Its update triggers a libtool rebuild since libtool uses some hard coded locations of gcc tools. Also linux and the likes are rebuild since there are soft checks by dkms which deny the module to have a different gcc version than the kernel at compile time.

GCC has some stability guarantees regarding it's ABI which are pretty solid for everything < C++11. After GCC 5.1 a rebuild has been rarely necessary. Although for programs using >= C++11 the ABI is changed more frequently. See libstdc++ ABI docs.

Due to historic experience with unsane gcc environments Arch rebuilds the whole toolchain on a major gcc version bump. This also ensures that no package of the toolchain is build with an outdated compiler.

Also the kernel has a strict check on gcc configure flags. So, if any flags are changed between package releases, even if it is the same gcc version, a kernel rebuild is required.

Rebuild on any gcc bump:

  • libtool
  • kernel

Rebuild on major gcc bump:

  • toolchain (bootstrap)
  • libtool
  • kernel

Other "Toolchain" Packages

These packages are closely tied to the toolchain, either as dependencies, or through the need for versioned rebuilds. Ideally these should be maintained by the toolchain team to ensure consistency.

  • libtool
  • libmpc
  • dejagnu
  • elfutils
  • sysprof
  • valgrind
  • mpfr