A Real Package: Cross-Compiling zlib

zlib is small, ubiquitous, and, conveniently for this lecture, a perfect example of a package that looks like Autotools but doesn’t quite behave like it. It ships its own hand-written configure script that predates widespread Autotools adoption in the project.

$ wget https://zlib.net/zlib-1.3.1.tar.gz
$ tar xf zlib-1.3.1.tar.gz
$ cd zlib-1.3.1

zlib’s configure script doesn’t accept the standard --host flag the way real Autotools packages do. Instead, you point it at your cross-compiler directly through the CC variable and skip the machine-role flags entirely:

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

The lesson here generalizes well beyond zlib: always read a package’s INSTALL or README file before assuming it follows textbook Autotools conventions, because plenty of well-established packages predate, or simply diverge from, the standard.

Package Configuration With pkg-config

Once a library is installed into your sysroot, the next problem is knowing exactly which compiler and linker flags any other package needs to use it. Tracking this by hand across dozens of packages is unmanageable, which is exactly the problem pkg-config solves. It reads small .pc metadata files, one per installed library, kept in [sysroot]/usr/lib/pkgconfig:

$ cat $(aarch64-linux-gnu-gcc -print-sysroot)/usr/lib/pkgconfig/zlib.pc
prefix=/usr
exec_prefix=${prefix}
libdir=${exec_prefix}/lib
includedir=${prefix}/include

Name: zlib
Description: zlib compression library
Version: 1.3.1
Libs: -L${libdir} -lz
Cflags: -I${includedir}

Querying it directly on your host will fail, though, and this catches almost everyone the first time:

$ pkg-config zlib --libs --cflags
Package zlib was not found in the pkg-config search path.

That’s because pkg-config defaults to searching your host’s own .pc database, not your target’s sysroot. Point it at the right place with PKG_CONFIG_LIBDIR:

$ PKG_CONFIG_LIBDIR=$(aarch64-linux-gnu-gcc -print-sysroot)/usr/lib/pkgconfig \
  pkg-config zlib --libs --cflags
-I/usr/include -L/usr/lib -lz

With that working, feeding the output straight into a cross-compile becomes one clean command:

$ PKG_CONFIG_LIBDIR=$(aarch64-linux-gnu-gcc -print-sysroot)/usr/lib/pkgconfig \
  aarch64-linux-gnu-gcc $(pkg-config zlib --cflags --libs) \
  ep_compress_demo.c -o ep_compress_demo

Where ep_compress_demo.c is a small original program calling zlib’s compress() and uncompress() functions to round-trip a short string, useful as a quick smoke test that the library, headers, and linker are all correctly wired together end to end.

When Cross-Compiling Gets Ugly

zlib and SQLite-style libraries cross-compile smoothly. Plenty of packages do not, and the pain almost always falls into one of a few recurring categories:

Each of these requires case-by-case detective work: reading configure logs, checking config.log, and sometimes patching the package’s build scripts directly. For any package with a genuinely large dependency graph, manually cross-compiling everything by hand stops being a good use of your time.

The Better Long-Term Answer

This is precisely the pain that Buildroot and the Yocto Project exist to eliminate. Both encode the cross-compilation quirks of hundreds of common packages so you don’t have to rediscover them yourself, generate a matched toolchain and sysroot automatically, and handle dependency graphs that would take weeks to resolve manually. Manual cross-compilation, package by package, is worth doing while you’re learning, exactly as this lecture series has done, but it is rarely the right approach for an entire production root filesystem.

Common Mistakes

Best Practices

Summary and Key Takeaways: the Whole Toolchain Series

Across this series you’ve gone from “what is a toolchain” to actually cross-compiling a real third-party library end to end. A toolchain is binutils, a compiler, a C library, and kernel headers, chosen deliberately and kept consistent for the life of a project. Cross toolchains dominate embedded development, and the ABI, C library, and floating-point choices baked into a toolchain’s target tuple matter more than most beginners expect. You can build a toolchain from source with crosstool-NG, or source a matched one from Bootlin, Arm’s official downloads, or your build system’s SDK. Static and dynamic linking trade size for patchability, and the soname system is what lets shared libraries evolve safely. Cross-compiling individual packages works with plain makefiles, Autotools, or increasingly CMake and Meson, and pkg-config is what stitches dependencies together correctly, as long as you remember to point it at your sysroot. And for anything beyond a handful of packages, a proper build system does this work far more reliably than doing it by hand.

With a solid toolchain foundation in place, the next stage of any embedded Linux project is the bootloader, the piece of software that brings your board to life and hands off control to the kernel you’ll build using exactly the toolchain skills covered here.

FAQ