Skip to main content
OpenWrt ships its own complete cross-compilation toolchain rather than relying on the host system’s compilers. This ensures reproducible builds, correct embedded-specific settings, and a sysroot that matches the target system exactly.

​
Why a Custom Toolchain?

  • Reproducibility: The same toolchain version is used regardless of what is installed on the build host.
  • Correct sysroot: The toolchain is built against the same C library (musl or glibc) that will run on the target device.
  • Embedded-specific tuning: Optimization flags, ABI choices, and floating-point handling are set for the target CPU.
  • Controlled GCC version: Security and optimization features (PIE, SSP, LTO) are configured consistently.

​
Toolchain Components

binutils

GNU assembler (as), linker (ld), and binary utilities (objcopy, strip, nm, etc.) for the target architecture.

GCC

GNU C/C++ compiler. Versions 12, 13, 14 (default), and 15 are supported. Built in three stages: minimal, initial, and final.

musl libc

The default C library for OpenWrt targets. Lightweight, standards-compliant, and suitable for embedded systems.

glibc (optional)

The GNU C Library. Available as an alternative to musl via menuconfig. Larger, but offers broader binary compatibility.

Kernel Headers

Linux kernel UAPI headers that define the system call interface between userspace and the kernel.

Host Tools

Build-time utilities compiled for the host machine: mkimage, mksquashfs, e2fsck, pkg-config, and more.

​
Toolchain Source Layout

toolchain/
  binutils/       # GNU binutils recipes
  gcc/            # GCC recipes and patches (12.x, 13.x, 14.x, 15.x)
  musl/           # musl libc recipe
  glibc/          # glibc recipe
  kernel-headers/ # Linux kernel UAPI headers
  wrapper/        # Flag-injection wrapper scripts
  mold/           # mold linker (optional)
  gdb/            # GDB debugger
  nasm/           # NASM assembler (for x86 host tools)
  fortify-headers/ # Fortification headers
  Config.in       # Toolchain menuconfig options

​
Building the Toolchain

# Build the complete toolchain
make toolchain/install

# Build only binutils
make toolchain/binutils/install

# Build only GCC
make toolchain/gcc/install

# Clean and rebuild from scratch
make toolchain/clean
make toolchain/install
The toolchain build is also triggered automatically as a dependency of the first make invocation that needs it.

​
Toolchain Output Location

After a successful build, the toolchain is installed into the staging directory: 
staging_dir/toolchain-<arch><suffix>_gcc-<version>_<libc>/
  bin/           # Cross-compiler binaries
  lib/           # Compiler runtime libraries
  usr/           # Include files and libraries for the target
  info.mk        # Toolchain metadata (version strings)
For example, for an ARM Cortex-A9 target with GCC 14 and musl: 
staging_dir/toolchain-arm_cortex-a9_gcc-14.3.0_musl_eabi/
  bin/arm-openwrt-linux-muslgnueabi-gcc
  bin/arm-openwrt-linux-muslgnueabi-g++
  bin/arm-openwrt-linux-muslgnueabi-ld.bfd
  ...

​
Host Tools

Build-time tools that run on the host (not the target) are installed in: 
staging_dir/host/bin/
  mkimage          # U-Boot image creation tool
  mksquashfs       # SquashFS filesystem creator
  mkhash           # OpenWrt hash utility
  pkg-config       # Library metadata query tool
  fakeroot         # Fake root for package building
  opkg             # Package manager (host version for image building)
  ...
These tools are built from the tools/ directory in the OpenWrt tree and are prerequisites for the target build.

​
Selecting the C Library

The default C library is musl. To switch to glibc: 
make menuconfig
# Navigate to: Advanced configuration options (for developers)
#   -> Toolchain Options
#     -> C Library implementation -> Use glibc
Switching the C library requires a full toolchain and package rebuild. musl and glibc produce binary-incompatible binaries.

​
External Toolchain

If you have a pre-existing cross-toolchain (e.g., from a vendor SDK), you can point OpenWrt to it: 
make menuconfig
# Navigate to: Advanced configuration options -> Toolchain Options
#   -> Use external toolchain
See toolchain/Config.in and scripts/ext-toolchain.sh for details.