meson --cross-file: Cross-Compiling in CI
meson setup --cross-file tells Meson to build for a different machine using a declarative toolchain file.
Cross-compiling C/C++ in CI (for ARM, embedded, or a different libc) is a first-class Meson feature driven by a cross file. The file names the compilers and target machine so meson.build stays portable.
What it does
A cross file is an INI-style file with [binaries], [host_machine], and optional [properties] sections naming the cross compiler, linker, and target architecture. meson setup --cross-file uses it to configure a build for the host (target) machine while running on the build machine. --native-file does the analogous thing for native overrides.
Common usage
meson setup build --cross-file aarch64.txt
# aarch64.txt
# [binaries]
# c = 'aarch64-linux-gnu-gcc'
# cpp = 'aarch64-linux-gnu-g++'
# strip = 'aarch64-linux-gnu-strip'
# pkg-config = 'aarch64-linux-gnu-pkg-config'
# [host_machine]
# system = 'linux'
# cpu_family = 'aarch64'
# cpu = 'aarch64'
# endian = 'little'Options
| Flag | What it does |
|---|---|
| --cross-file <file> | Toolchain definition for the target machine |
| --native-file <file> | Overrides for the build (native) machine |
| [binaries] | Section naming c, cpp, ar, strip, pkg-config |
| [host_machine] | Target system, cpu_family, cpu, endian |
| [properties] | Extra settings like sys_root and needs_exe_wrapper |
In CI
Commit cross files to the repo and select one per matrix leg so the same meson.build cross-compiles for every target. Set a target-specific pkg-config in [binaries] so dependency discovery looks at the sysroot, not the host. Provide an exe_wrapper (for example qemu) if tests must run cross-built binaries.
Common errors in CI
"Cross file does not exist" means a wrong path to --cross-file. "Executables created by c compiler ... are not runnable" means tests tried to run target binaries without an exe_wrapper; add one or skip running cross binaries. pkg-config finding host libraries instead of target ones means the cross pkg-config (and PKG_CONFIG_LIBDIR) is not set in the cross file.