Having a Toolchain Is Only the Beginning

A working cross toolchain gets you nowhere by itself. The real work is cross-compiling the dozens or hundreds of open source packages your embedded Linux system actually depends on, and almost none of them were originally written with cross-compilation as the primary use case. Each build system handles this differently, and knowing which one you’re dealing with saves hours of guessing.

The Easy Case: Plain Makefiles

Some of the most important pieces of an embedded Linux system, including the Linux kernel itself, the U-Boot bootloader, and BusyBox, use hand-written makefiles that already understand cross-compilation through one convention: a CROSS_COMPILE make variable holding your toolchain’s prefix, trailing dash included.

$ make CROSS_COMPILE=aarch64-linux-gnu-

Or, exported once for a whole session:

$ export CROSS_COMPILE=aarch64-linux-gnu-
$ make

For the kernel and U-Boot specifically, you also need to set the target ARCH, which selects the correct architecture-specific source directories:

$ make ARCH=arm64 CROSS_COMPILE=aarch64-linux-gnu-

Autotools: the Older, Still-Common Standard

Autotools is not one tool but a family: Autoconf, Automake, Libtool, and Gnulib, working together to smooth over differences between build environments, compiler versions, and library locations across many different Linux and Unix systems. Packages that use it ship a configure script that probes your environment and generates the right makefiles.

$ ./configure --help

For a native build, the classic three-step dance is enough:

$ ./configure
$ make
$ sudo make install

Cross-compiling needs a few more environment variables set correctly:

Why –host Matters More Than CC Alone

Setting CC alone is sometimes enough, but you will frequently hit an error like this:

checking whether we are cross compiling... configure: error:
  cannot run C compiled programs.
If you meant to cross compile, use '--host'.

The reason: configure often tests the toolchain’s capabilities by compiling small snippets and actually running them, which is impossible when the output binary is built for a different architecture than the host running the script. Autotools distinguishes three machine roles to solve this properly:

Setting --host correctly is what actually tells configure to trust your explanation instead of trying to execute cross-compiled test binaries:

$ CC=aarch64-linux-gnu-gcc \
  ./configure --host=aarch64-linux-gnu --prefix=/usr

The --prefix=/usr matters too: left at its default, Autotools installs into <sysroot>/usr/local, which most systems don’t search by default. Setting the prefix to /usr ensures headers and libraries land where the rest of your sysroot expects to find them.

Try It: Cross-Compiling a Small Original Library

Rather than reusing any specific book example, build a tiny original Autotools-style project, ep_greet, and install it directly into your toolchain’s sysroot for testing:

$ CC=aarch64-linux-gnu-gcc \
  ./configure --host=aarch64-linux-gnu --prefix=/usr
$ make
$ make DESTDIR=$(aarch64-linux-gnu-gcc -print-sysroot) install

Setting DESTDIR is essential here. Without it, make install tries to write into your host machine’s real /usr directory, which is never what you want when cross-compiling. With it, the freshly built library and headers land inside your toolchain’s sysroot instead, exactly where later builds will expect to find them.

Where CMake and Meson Fit In

Autotools was the default for decades, but it is no longer the only serious option. CMake has become extremely common for C and C++ projects, including many modern embedded frameworks, and it handles cross-compilation through a toolchain file rather than environment variables:

$ cmake -DCMAKE_TOOLCHAIN_FILE=aarch64-toolchain.cmake -B build
$ cmake --build build

A minimal toolchain file just points CMake at your cross-compiler and sysroot:

# aarch64-toolchain.cmake
set(CMAKE_SYSTEM_NAME Linux)
set(CMAKE_SYSTEM_PROCESSOR aarch64)
set(CMAKE_C_COMPILER aarch64-linux-gnu-gcc)
set(CMAKE_FIND_ROOT_PATH /opt/toolchains/aarch64-linux-gnu/aarch64-linux-gnu/sysroot)

Meson, a newer build system that generates Ninja build files under the hood, takes a similar cross-file approach and has been gaining adoption for its speed and simpler syntax. None of these has fully displaced Autotools, since thousands of existing packages still use it, but for new embedded projects it’s worth knowing all three exist rather than assuming Autotools is the only path.

Common Mistakes

Best Practices

Summary and Key Takeaways

Kernel-style makefiles need only CROSS_COMPILE and, for the kernel and U-Boot, ARCH. Autotools packages need CC and, critically, –host, plus a correctly set –prefix and DESTDIR when installing into a sysroot. And while Autotools still underpins a huge share of the open source world, CMake and Meson have earned real footing in newer embedded projects and are worth knowing alongside it, not instead of it.

In the final lecture of this series, we cross-compile a real third-party package end to end, resolve its dependencies with pkg-config, and cover what to do when cross-compilation doesn’t go smoothly.

FAQ