docker-arm-cross-toolchain

Repository with ARM cross-compilation toolchains (mainly for Raspberry Pi), available as stand-alone tarballs or Docker containers.

• GCC: 14.2, 13.3, 12.4
• Languages: C, C++, Fortran
• Glibc: 2.31 and later
• Linux: 5.4 and later
• Distributions: Ubuntu 20.04 Focal, Raspberry Pi OS 11 Bullseye, Rocky 9 and later

The toolchains are built using crosstool-NG.
The Linux compilers include the address and undefined behavior sanitizers (Asan and UBsan) and gdbserver (15.1). They are compatible with glibc 2.31 and Linux 5.4 or later, and have been patched for Debian Multiarch.
The bare-metal compilers ship with newlib 4.4 and newlib-nano 4.3.

The toolchains themselves can be used on any x86-64 system running Ubuntu 18.04 Bionic, Debian 10 Buster, Rocky 8 (or later), or on a Raspberry Pi running 64-bit Ubuntu 20.04 Bionic, 64-bit Raspberry Pi OS 11 Bullseye (or later).

Download

The ready-to-use toolchain tarballs can be downloaded from the Releases page (no Docker required).
Direct links are available in the table below:

Target triplet	GCC 14.2	GCC 13.3	GCC 12.4	Recommended hardware	Supported distributions
aarch64-rpi3-linux-gnu	⬇️ x86-64 ⬇️ arm64	⬇️ x86-64 ⬇️ arm64	⬇️ x86-64 ⬇️ arm64	64-bit ARMv8: RPi 2B rev. 1.2, RPi 3B/3B+, CM 3, RPi 4B/400, CM 4, RPi Zero 2 W, RPi 5	Ubuntu 20.04 Focal, Debian 11 Bullseye, Rocky 9 and later
armv8-rpi3-linux-gnueabihf	⬇️ x86-64 ⬇️ arm64	⬇️ x86-64 ⬇️ arm64	⬇️ x86-64 ⬇️ arm64	32-bit ARMv8: RPi 2B rev. 1.2, RPi 3B/3B+, CM 3, RPi 4B/400, CM 4, RPi Zero 2 W, RPi 5	Ubuntu 20.04 Focal, Debian 11 Bullseye and later
armv6-rpi-linux-gnueabihf	⬇️ x86-64 ⬇️ arm64	⬇️ x86-64 ⬇️ arm64	⬇️ x86-64 ⬇️ arm64	32-bit ARMv6: RPi A/B/A+/B+, CM 1, RPi Zero/Zero W	Raspberry Pi OS 11 Bullseye and later
arm-pico-eabi	⬇️ x86-64 ⬇️ arm64	⬇️ x86-64 ⬇️ arm64	⬇️ x86-64 ⬇️ arm64	32-bit ARM Cortex-M0+: RP2040, RPi Pico, RPi Pico W	Raspberry Pi Pico SDK 2.0.0
arm-pico2-eabi	⬇️ x86-64 ⬇️ arm64	⬇️ x86-64 ⬇️ arm64	⬇️ x86-64 ⬇️ arm64	32-bit ARM Cortex-M33: RP2350, RPi Pico 2	Raspberry Pi Pico SDK 2.0.0

For modern Raspberry Pi boards running 64-bit Raspberry Pi OS or 64-bit Ubuntu, use the aarch64-rpi3-linux-gnu toolchain.
For modern Raspberry Pi boards running 32-bit Raspberry Pi OS, use the armv8-rpi3-linux-gnueabihf toolchain.
For older Raspberry Pi boards, or if you need to support all boards, use the armv6-rpi-linux-gnueabihf toolchain.

See www.raspberrypi.com/documentation/computers/processors.html for an overview of the processors used by different Raspberry Pi models.

There is no specific toolchain for the first version of the RPi 2B (which uses a quad-core ARMv7 Cortex-A7), but the armv6-rpi-linux-gnueabihf toolchain is compatible with this architecture as well.

For the RPi 5, RPi 4B/400 and the CM 4, use the aarch64-rpi3-linux-gnu or the armv8-rpi3-linux-gnueabihf toolchain, depending on whether you're using a 64-bit or a 32-bit operating system. For optimal performance, you can include the -mcpu=cortex-a76+crypto (RPi 5) or -mcpu=cortex-a72 (RPi 4) flag (GCC ARM options).

For the Raspberry Pi Pico and other RP2040-based boards, use the bare-metal arm-pico-eabi toolchain.

Installation

Download the archive of the toolchain you need using the links above. Then extract it to a convenient location, e.g. ~/opt.

You can download and extract the toolchain in one go using wget and tar, for example:

mkdir -p ~/opt
wget https://github.com/tttapa/docker-arm-cross-toolchain/releases/latest/download/x-tools-aarch64-rpi3-linux-gnu-gcc14.tar.xz -O- | tar xJ -C ~/opt

If you want to use the toolchain directly, you can add the ~/opt/x-tools/aarch64-rpi3-linux-gnu/bin folder to your path:

export PATH="$HOME/opt/x-tools/aarch64-rpi3-linux-gnu/bin:$PATH"

To make it permanent, you can add it to your ~/.profile:

echo 'export PATH="$HOME/opt/x-tools/aarch64-rpi3-linux-gnu/bin:$PATH"' >> ~/.profile

To verify that the toolchain was successfully added to the path, try querying the GCC version:

aarch64-rpi3-linux-gnu-gcc --version

Usage

CMake

For new software configured using CMake, simply specify the appropriate toolchain file. Several toolchain files are included with the toolchain, and you can wrap them in a custom toolchain file if you need finer control. See the cmake directory for an overview of available toolchain files.

For example:

cd my-cmake-project # Open the directory of your CMake project
triple=aarch64-rpi3-linux-gnu # Select the main toolchain
variant_triple=aarch64-rpi4-linux-gnu # Select a specific variant
# Configure
cmake -S . -B build-$variant_triple --toolchain ~/opt/x-tools/$triple/$variant_triple.toolchain.cmake
# Build
cmake --build build-$variant_triple -j

On older versions of CMake, you might have to use -DCMAKE_TOOLCHAIN_FILE="$HOME/opt/x-tools/$triple/$variant_triple.toolchain.cmake" instead of --toolchain ~/opt/x-tools/$triple/$variant_triple.toolchain.cmake.

I highly recommend using CMake for your own projects as well, this makes it much easier for other people to depend on, package, and cross-compile your software.
See Mastering CMake: Cross Compiling with CMake and the cmake-toolchains(7) manpage for more details about CMake toolchain files.

For more detailed instructions on how to cross-compile software and how to handle dependencies, see https://tttapa.github.io/Pages/Raspberry-Pi/index.html.

VSCode CMake Tools Extension

To pass the --toolchain option to CMake when using the CMake Tools extension, add the paths to the different toolchain files to a “kits” file, either globally (Ctrl+Shift+P, Edit User-Local CMake Kits) or for the specific project (in .vscode/cmake-kits.json). Then select this toolchain using Ctrl+Shift+P, CMake: Select a Kit.

For example, cmake-kits.json could contain:

[
    {
        "name": "Raspberry Pi 5 (64-bit, GCC)",
        "toolchainFile": "${env:HOME}/opt/x-tools/aarch64-rpi3-linux-gnu/aarch64-rpi5-linux-gnu.toolchain.cmake"
    }
]

A full kits file with all toolchains is included: cmake/cmake-kits.json.

See the CMake Tools documentation for more details.

Manual compiler invocation

To invoke a compiler or other tools manually, simply add the bin folder of the toolchain to your path, as explained above.

Then invoke the compiler you need, for example:

cat > hello.c << EOF
#include <stdio.h>
int main(void) { puts("Hello, world!"); }
EOF
aarch64-rpi3-linux-gnu-gcc hello.c -o hello
aarch64-rpi3-linux-gnu-readelf -h hello

Note that the compilers have been configured to use the most compatible target by default (e.g. the Raspberry Pi 3 for aarch64-rpi3-linux-gnu), so you might have to specify additional flags to select the one that fits your needs (e.g. -mcpu=cortex-a72+crc+simd for the Raspberry Pi 4). See the flags used in the CMake toolchain files in the cmake directory for inspiration.

Autotools, Make and other legacy build tools

For legacy software configured using Autotools, you usually have to pass the --host flag (e.g. --host="aarch64-rpi3-linux-gnu") to the configure script.
Packages with custom configuration scripts might have differently named options, for example, OpenSSL has --cross-compile-prefix="aarch64-rpi3-linux-gnu-".
Custom Makefiles might require you to set a variable such as CROSS=aarch64-rpi3-linux-gnu- or CROSS_COMPILE=aarch64-rpi3-linux-gnu-.
If all else fails, try setting the CC, CXX or FC environment variables explicitly.

Pico SDK

To use the arm-pico-eabi toolchain for the Raspberry Pi Pico with the Pico SDK, set the PICO_SDK_PATH environment variable when invoking the CMake configure command, and use the provided toolchain file:

export PICO_SDK_PATH="$HOME/pico/pico-sdk"
cmake -S . -B build --toolchain ~/opt/x-tools/arm-pico-eabi/arm-pico-eabi.toolchain.cmake # ...
cmake --build build -j # ...

If you're using Visual Studio Code with the CMake Tools extension, create a file .vscode/cmake-kits.json with the following contents:

[
    {
        "name": "Raspberry Pi Pico (GCC)",
        "toolchainFile": "${env:HOME}/opt/x-tools/arm-pico-eabi/arm-pico-eabi.toolchain.cmake",
        "environmentVariables": {"PICO_SDK_PATH": "${env:HOME}/pico/pico-sdk"}
    }
]

Then select this toolchain using Ctrl+Shift+P, CMake: Select a Kit.

The .vscode/cmake-kits.json file is also included in this repository: cmake/cmake-kits.json.

Alternative approach without a toolchain file ...

If you don't want to use a toolchain file, it is possible to select the correct toolchain using environment variables:

export PICO_SDK_PATH="$HOME/pico/pico-sdk"
export PICO_GCC_TRIPLE="arm-pico-eabi"
export PICO_TOOLCHAIN_PATH="$HOME/opt/x-tools/arm-pico-eabi/bin"
cmake -S . -B build # ...
cmake --build build -j # ...

If you're using Visual Studio Code with the CMake Tools extension, you can add the following to .vscode/settings.json:

{
    "cmake.configureEnvironment": {
        "PICO_GCC_TRIPLE": "arm-pico-eabi",
    }
}

Alternatively, create a file .vscode/cmake-kits.json with the following contents:

[
    {
        "name": "RPi Pico",
        "environmentVariables": {
            "PICO_SDK_PATH": "${env:HOME}/pico/pico-sdk",
            "PICO_GCC_TRIPLE": "arm-pico-eabi",
            "PICO_TOOLCHAIN_PATH": "${env:HOME}/opt/x-tools/arm-pico-eabi/bin"
        }
    }
]

Deployment

Recent versions of GCC require recent versions of the C++ standard library, libstdc++. If the operating system on the Raspberry Pi you want to deploy to uses an older version of libstdc++, you have multiple options:

• Link the C++ standard library statically, using the -static-libstdc++ flag. This results in slightly larger binaries, but improves portability.
• Install a newer version of the C++ standard library globally by copying x-tools/aarch64-rpi3-linux-gnu/aarch64-rpi3-linux-gnu/sysroot/lib64/libstdc++.so.6.0.* from the toolchain to the /usr/local/lib/aarch64-linux-gnu folder on the Pi, and run sudo ldconfig.
• Ship a copy of libstdc++ with your application, and ensure that it is loaded before the global one, by using the -rpath flag or the LD_LIBRARY_PATH environment variable. This may not be an option if your binary is loaded by another program (e.g. Python modules).
• Use a Docker container with a recent version of the C++ standard library.

Other libraries, such as libasan.so can be installed similarly.

Note that this is not at all true for the C standard library, libc.so. The C standard library is tightly coupled to the rest of the system, and cannot be replaced by a newer version.

ABI compatibility

If you plan to link code compiled using these toolchains to libraries that are provided by Raspberry Pi OS, you should use the armv6-rpi-linux-gnueabihf toolchain for 32-bit RPi OS or the aarch64-rpi3-linux-gnu toolchain for 64-bit RPi OS. Even though using the armv8-rpi3-linux-gnueabihf toolchain may result in significantly more performant binaries, they may not be compatible with libraries that were compiled for the ARMv6 architecture (which includes all libraries that are part of Raspberry Pi OS). For instance, the std::shared_ptr ABI is different between the armv8-rpi3-linux-gnueabihf and armv6-rpi-linux-gnueabihf toolchains.

If you compile all your libraries from source using the same toolchain (e.g. using a package manager) and link them statically, ABI incompatibility is usually less of a concern.

Common issues

• /usr/lib/aarch64-linux-gnu/libstdc++.so.6: version GLIBCXX_3.4.33 not found:
  This means that the available version of the C++ standard library is too old. See §Deployment for instructions to resolve this issue.
• /lib64/libc.so.6: version ``GLIBC_2.31' not found:
  Your operating system is too old. Use a newer operating system, or an older version of the toolchain. Note that upgrading glibc is not possible.
• Could NOT find Threads (missing: Threads_FOUND):
  See tttapa/RPi-Cross-Cpp-Development#2 (comment) for a fix.