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).
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.
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
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.
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.
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.
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.
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"
}
}
]
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 runsudo 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 theLD_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.
/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.