DeveloperWiki:Toolchain maintenance

From ArchWiki
Jump to navigation Jump to search

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 -> binutils -> glibc

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.

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.

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.

  • TODO: document reason for rsync as a makedepends
  • 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

The binutils package provides set of programs to assemble and manipulate binary and object files.


The binutils PKGBUILD is set up to use either release tarballs or git checkouts. As binutils rarely releases bug fix releases, it can be useful to build off the release branch to get important backports. Alternatively, maintainers can select individual patches to include and work with the release tarball which has a PGP signature.

If building from release tarballs, we symlink the release directory to "binutils-gdb" during the prepare() function to unify the build process. Additionally, release branches in git are labelled as developmental builds, so we adjust "bfd/" to set this as a release build.

Preparing the Build

Binutils can only be built outside the source tree, so we create a "binutils-build" directory. Using "makepkg -p" is to allow for incremental builds when testing package changes (and is useless during clean chroot builds).

Libiberty configures using "$CPP $CPPFLAGS" which fails using Arch default flags as FORTIFY_SOURCE requires optimisation provided in CFLAGS. We add -O2 the the relevant line in libiberty/configure.

TODO: A potential better solution is to move -D_FORTIFY_SOURCE=2 to CFLAGS (using -Wp,), either in the PKGBUILD or at Arch level. This may also fix testsuite failures (below)

Configuring the Build

The following configure options are used in the binutils build:

Set the default paths in Arch:


We use our bug tracker as the first point of call for Arch users (and derivatives that distribute out packages...):


Options added to enable our unified git/tarball PKGBUILD:


We build the gold linker, but still use the bfd linker as our default, and enable threading when using gold. There may be benefits in Arch switching to used gold as default at some stage:


Enable link time optimization support:


Enables plugin support for the linker:


Enable -z,relro by default. This is enabled as a security feature.:


TODO: is -z,relro needed in makepkg.conf?

Try to use only PIC objects:


Create reproducible archives - zero for UIDs, GIDs, timestamps, and use consistent file modes for all files:


Support Intel CET instructions:


Build the BFD and opcodes libraries as shared libraries, which we then delete during packaging...:


TODO: confirm this is as dumb as it seems

Enable producing EFI binaries - useful for setting up UEFI boot with Xen:


Enable debuginfo lookups with debuginfod:


Use the system zlib library rather than the copy in the binutils source:



It is important that the Arch LDFLAGS are overridden before running the binutils testsuite. The testsuite makes decisions of which LDFLAGS to include while test various features, and does not ignore values from the build environment.

Failures in the ld.bfd linker testsuite need examined in detail and documented before release of any package. As is not the default linker, we allow failures in its testsuite. These failures in the gold testsuite have historically been false positives due to the Arch buildflags.

The following tests are the current (binutils-2.35.1) known to fail in the gold testsuite:


TODO: investigate these failures and document reasons. Note testsuite attempts to remove FORTIFY_SOURCE, but assumes it is specified with -Wp in CFLAGS rather than directly in LDFLAGS.

Packaging Notes

We remove man pages for utilities that we do not distribute (Windows/Novell only).

We also prevent programs from dynamically linking against libbfd and libopcodes, as these are rather unstable. Instead, we provide linker scripts to link the static versions (and their dependencies).

GNU Compiler Collection

Provided by gcc.

Last (or first) step of the toolchain, and vital to building its entirety. Its update triggers a binutils and glibc rebuild, as well as other packages, like linux itself and libtool

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.