Cross-Compilation

Using the OpenWrt cross-compiler to build software for the target architecture on a host machine.

Cross-compilation is the process of building binaries for a target CPU architecture on a host machine with a different architecture (typically an x86-64 development workstation building for a MIPS or ARM router).

Cross-Compiler Naming Convention

OpenWrt cross-compiler binaries follow this naming pattern:

<arch>-openwrt-linux-<libc>-<tool>

Examples:

mips-openwrt-linux-musl-gcc         # MIPS + musl
aarch64-openwrt-linux-musl-gcc      # AArch64 + musl
arm-openwrt-linux-muslgnueabi-gcc   # ARM (EABI) + musl
x86_64-openwrt-linux-musl-gcc       # x86-64 + musl

All cross-compiler binaries are located in:

staging_dir/toolchain-<arch><suffix>_gcc-<version>_<libc>/bin/

STAGING_DIR and the Sysroot

The STAGING_DIR environment variable points to the directory that contains headers and libraries for the target system. It acts as a sysroot: the cross-compiler looks here for #include files and -l libraries instead of the host system paths.

staging_dir/target-<arch>_<libc>/
  usr/
    include/    # Header files for target libraries
    lib/        # Shared libraries for the target
  root-<board>/ # Staged rootfs (installed package contents)

Using the Toolchain for External Packages

You can use the OpenWrt toolchain to cross-compile any external software. The key is to set up STAGING_DIR and add the toolchain’s bin/ directory to PATH.

Basic Setup

# Set STAGING_DIR to the target staging directory
export STAGING_DIR="$(pwd)/staging_dir/target-mips_24kc_musl"

# Add the toolchain binaries to PATH
export PATH="$(pwd)/staging_dir/toolchain-mips_24kc_gcc-14.3.0_musl/bin:$PATH"

# Compile a simple program
mips-openwrt-linux-musl-gcc -o hello hello.c

Using pkg-config

OpenWrt installs a host pkg-config in staging_dir/host/bin/ configured to search the target sysroot:

export PKG_CONFIG="$(pwd)/staging_dir/host/bin/pkg-config"
export PKG_CONFIG_PATH="$STAGING_DIR/usr/lib/pkgconfig"

# Query a library
pkg-config --cflags --libs libubox

Cross-Compiling a Configure-Based Package

export STAGING_DIR="$(pwd)/staging_dir/target-mips_24kc_musl"
export PATH="$(pwd)/staging_dir/toolchain-mips_24kc_gcc-14.3.0_musl/bin:$PATH"
export PKG_CONFIG="$(pwd)/staging_dir/host/bin/pkg-config"

CROSS=mips-openwrt-linux-musl-

./configure \
  --host=mips-openwrt-linux-musl \
  --prefix=/usr \
  CC=${CROSS}gcc \
  CXX=${CROSS}g++ \
  AR=${CROSS}gcc-ar \
  RANLIB=${CROSS}gcc-ranlib \
  CFLAGS="-Os -pipe" \
  LDFLAGS="-L$STAGING_DIR/usr/lib" \
  CPPFLAGS="-I$STAGING_DIR/usr/include"

make

Build Environment Variables

When building packages inside the OpenWrt build system, these variables are automatically set:

Variable	Value
TARGET_CROSS	Cross-compiler prefix, e.g. mips-openwrt-linux-musl-
TARGET_CC	$(TARGET_CROSS)gcc
TARGET_CXX	$(TARGET_CROSS)g++
TARGET_AR	$(TARGET_CROSS)gcc-ar
TARGET_RANLIB	$(TARGET_CROSS)gcc-ranlib
TARGET_CFLAGS	Target optimization and arch flags
TARGET_CXXFLAGS	Same as TARGET_CFLAGS
TARGET_LDFLAGS	Linker flags including toolchain library paths
STAGING_DIR	Target sysroot directory
PKG_CONFIG	Host pkg-config configured for the sysroot

Using the Image Builder’s External Toolchain

The scripts/ext-toolchain.sh script can help configure an external toolchain for use with OpenWrt:

./scripts/ext-toolchain.sh --toolchain /opt/my-toolchain \
  --with-libc musl \
  --config mips_24kc

When cross-compiling packages for use with OpenWrt, always link against the libraries in staging_dir/ rather than host system libraries to ensure ABI compatibility with the target device.