When CMake cross-compiles a project from an x86 workstation for a Linux ARM board, what belongs in the toolchain file, and when does CMake read it?
answer
- describe the target, not the project
- CMAKE_SYSTEM_NAME turns on cross
- compilers fixed at first configure
- read again for try_compile
- CMAKE_CURRENT_LIST_DIR, not CMAKE_SOURCE_DIR
basics
~20 sThe toolchain file describes the target: CMAKE_SYSTEM_NAME and CMAKE_SYSTEM_PROCESSOR, the cross compilers, an optional CMAKE_SYSROOT and the find-root modes. It is passed with --toolchain or CMAKE_TOOLCHAIN_FILE when the build tree is first configured, and read before compiler detection.
solid answer
~40 sA toolchain file is a small CMake script about the **target platform**, kept out of `CMakeLists.txt`. It sets `CMAKE_SYSTEM_NAME` (here `Linux`; setting it is what makes `CMAKE_CROSSCOMPILING` true), `CMAKE_SYSTEM_PROCESSOR` (`aarch64`), `CMAKE_C_COMPILER` and `CMAKE_CXX_COMPILER` (a GNU cross compiler, or `clang++` plus `CMAKE_CXX_COMPILER_TARGET`), usually `CMAKE_SYSROOT`, and the `CMAKE_FIND_ROOT_PATH_MODE_*` variables. You pass it with `cmake --toolchain arm.cmake` (CMake 3.21+) or `-DCMAKE_TOOLCHAIN_FILE=...` when the build tree is created; CMake loads it before `project()` detects compilers, may load it more than once, and also uses it for `try_compile` test projects, so it must be idempotent and use `CMAKE_CURRENT_LIST_DIR` for paths. Compilers cannot be changed later: changing `CMAKE_CXX_COMPILER` in an existing tree deletes the cache, so a new toolchain means a fresh build directory.
code
cmake · 15 lines# arm-linux.cmake: a Linux aarch64 board, clang as the cross compiler
set(CMAKE_SYSTEM_NAME Linux)
set(CMAKE_SYSTEM_PROCESSOR aarch64)
set(CMAKE_SYSROOT ${CMAKE_CURRENT_LIST_DIR}/sysroot)
set(CMAKE_C_COMPILER clang)
set(CMAKE_C_COMPILER_TARGET aarch64-linux-gnu)
set(CMAKE_CXX_COMPILER clang++)
set(CMAKE_CXX_COMPILER_TARGET aarch64-linux-gnu)
set(CMAKE_TRY_COMPILE_TARGET_TYPE STATIC_LIBRARY)
set(CMAKE_FIND_ROOT_PATH_MODE_PROGRAM NEVER)
set(CMAKE_FIND_ROOT_PATH_MODE_LIBRARY ONLY)
set(CMAKE_FIND_ROOT_PATH_MODE_INCLUDE ONLY)
set(CMAKE_FIND_ROOT_PATH_MODE_PACKAGE ONLY)go deeper
Recall that cross builds pass a toolchain file with --toolchain, and that it names the target system and the cross compilers.
Explain each variable in a typical file, why CMAKE_SYSTEM_NAME turns on cross-compiling, and why the file must be given on the first configure.
Write toolchain files that survive being loaded for try_compile, use CMAKE_CURRENT_LIST_DIR, and treat a compiler change as a new build directory.
Own toolchain files as versioned team assets, one per target, so developers and CI build the board image the same way.
## What a toolchain file is for When CMake builds for the machine it runs on, it detects the compilers and the platform by itself. **Cross-compiling** means building on one system (the **host**, an x86 Linux workstation) for another (the **target**, an ARM board running Linux). CMake cannot guess the target, so a **toolchain file** tells it. It is an ordinary CMake script, but it describes the platform and compilers only; the project's `CMakeLists.txt` stays free of compiler paths, and the same project builds natively or for the board depending on which toolchain file is passed. ## What goes in it A toolchain file for the board, using clang as the cross compiler: ```cmake set(CMAKE_SYSTEM_NAME Linux) set(CMAKE_SYSTEM_PROCESSOR aarch64) set(CMAKE_SYSROOT ${CMAKE_CURRENT_LIST_DIR}/sysroot) set(CMAKE_C_COMPILER clang) set(CMAKE_C_COMPILER_TARGET aarch64-linux-gnu) set(CMAKE_CXX_COMPILER clang++) set(CMAKE_CXX_COMPILER_TARGET aarch64-linux-gnu) set(CMAKE_FIND_ROOT_PATH_MODE_PROGRAM NEVER) set(CMAKE_FIND_ROOT_PATH_MODE_LIBRARY ONLY) set(CMAKE_FIND_ROOT_PATH_MODE_INCLUDE ONLY) set(CMAKE_FIND_ROOT_PATH_MODE_PACKAGE ONLY) ``` | Variable | Meaning | |---|---| | `CMAKE_SYSTEM_NAME` | the target operating system; setting it manually makes `CMAKE_CROSSCOMPILING` true | | `CMAKE_SYSTEM_PROCESSOR` | the target architecture, which the file should set to match the compiler | | `CMAKE_<LANG>_COMPILER` | full path or name of the cross compiler, such as `aarch64-linux-gnu-g++` | | `CMAKE_<LANG>_COMPILER_TARGET` | the target triple for compilers that are cross compilers by design, such as clang | | `CMAKE_SYSROOT` | passed to the compiler as `--sysroot` and used to prefix `find_*` searches | | `CMAKE_FIND_ROOT_PATH_MODE_*` | whether `find_*` searches the target roots, the host, or both | With a GNU cross toolchain you would set `CMAKE_CXX_COMPILER` to the `aarch64-linux-gnu-g++` path and leave out `CMAKE_CXX_COMPILER_TARGET`. When a bare-metal toolchain cannot link an executable without a linker script, `CMAKE_TRY_COMPILE_TARGET_TYPE` set to `STATIC_LIBRARY` stops CMake's compiler checks from linking. ## How and when CMake reads it 1. It is passed with `cmake --toolchain path/arm.cmake` (CMake 3.21+) or `-DCMAKE_TOOLCHAIN_FILE=path/arm.cmake`, or from the `CMAKE_TOOLCHAIN_FILE` environment variable when a tree is first created. A relative path is tried against the build directory, then the source directory. 2. CMake loads it **early**, before the first `project()` call enables languages and detects compilers. Setting `CMAKE_CXX_COMPILER` after `project()` in `CMakeLists.txt` is too late. 3. CMake loads it **more than once**, and the documentation notes it is also used for the test projects that `try_compile` and the compiler checks generate. In a run of CMake 4.4.4, a `message()` in the file printed twice during the first configure of the main project, and a `list(APPEND CMAKE_CXX_FLAGS_INIT "-DX")` in it left `CMAKE_CXX_FLAGS` cached as `-DX;-DX`, which broke the compiler check. Hence: - use `CMAKE_CURRENT_LIST_DIR` for paths, because `CMAKE_SOURCE_DIR` and `CMAKE_BINARY_DIR` differ inside those test projects; - keep the file **idempotent**: plain `set()` calls, no `list(APPEND ...)` that grows on each load; - a custom `-D` variable the file depends on is passed into those test projects by listing it in `CMAKE_TRY_COMPILE_PLATFORM_VARIABLES`. ## Compilers are fixed for the life of the tree `CMAKE_<LANG>_COMPILER` cannot be changed once a build tree is configured. Passing `-DCMAKE_CXX_COMPILER=g++` to an existing cross tree makes CMake print "You have changed variables that require your cache to be deleted" and re-run configure from scratch. In a run of CMake 4.4.4 that also dropped `CMAKE_TOOLCHAIN_FILE` from the cache, and the tree silently became a host build (`CMAKE_SYSTEM_NAME` back to the host's). A different compiler or toolchain file therefore gets a new build directory, or `--fresh` with the toolchain passed again. ## Mistakes that show up in review - **Compiler paths in `CMakeLists.txt`.** They tie the project to one machine and, after `project()`, run too late; they belong in the toolchain file or in `-D` on the first configure. - **Forgetting `CMAKE_SYSTEM_PROCESSOR`.** When cross-compiling, CMake expects the toolchain file to set it to match the compiler; left out, it was empty in a CMake 4.4.4 run, so projects that branch on the architecture misbehave. - **Setting `CMAKE_CROSSCOMPILING` by hand.** CMake sets it from `CMAKE_SYSTEM_NAME`; the CMake documentation also warns that for Apple device builds it is not a reliable signal. - **Absolute paths to one developer's home directory.** Paths relative to `CMAKE_CURRENT_LIST_DIR`, or an environment variable read with `$ENV{...}`, let the same file work on every machine and in CI. - **Expecting a second configure to pick up a new toolchain file.** It must be given when the tree is created; switch with a fresh directory. ## Visual Studio is different For the Windows half of a project, the Visual Studio generators choose compilers through the IDE's own mechanism: `-A x64` or `-A ARM64` picks the target architecture (`CMAKE_GENERATOR_PLATFORM`) and `-T` picks a toolset (`CMAKE_GENERATOR_TOOLSET`). The CMake documentation says `CMAKE_<LANG>_COMPILER` is computed automatically for IDE generators and should not be set; a toolchain file may still initialise the platform and toolset variables.
- How do you run the board's unit tests or try_run checks on the x86 workstation during a cross build?Set `CMAKE_CROSSCOMPILING_EMULATOR` in the toolchain file to a host command that can run target binaries, such as a user-mode emulator for aarch64. CMake uses it for `try_run` and as the default `CROSSCOMPILING_EMULATOR` property of executables, which prefixes `add_test(NAME ... COMMAND ...)` commands and custom commands that run built target executables.
- Why should a toolchain file avoid list(APPEND CMAKE_CXX_FLAGS_INIT ...) style accumulation?CMake loads the toolchain file more than once, and also uses it for `try_compile` test projects. In a CMake 4.4.4 run, one `list(APPEND CMAKE_CXX_FLAGS_INIT "-DX")` produced `-DX;-DX` in the cached `CMAKE_CXX_FLAGS`, and the semicolon broke the compiler check. Plain `set()` of a complete value keeps the file idempotent.
- Where should a cross build install, given that CMAKE_INSTALL_PREFIX is where files live on the board?`CMAKE_INSTALL_PREFIX` stays the runtime location on the target, such as `/usr/local`. `CMAKE_STAGING_PREFIX`, set in the toolchain file, is a host directory that `cmake --install` writes to instead, which keeps a read-only sysroot pristine; CMake also searches it with `find_*`.
- The cross compiler is set with set(CMAKE_CXX_COMPILER ...) after project() in CMakeLists.txt
- CMAKE_CROSSCOMPILING must be set to TRUE in the toolchain file
- The toolchain file is read exactly once per configure, so appending to variables is safe
- Changing CMAKE_CXX_COMPILER on an existing build tree just swaps the compiler
- Paths in a toolchain file should use CMAKE_SOURCE_DIR
- Visual Studio builds pick their compiler by setting CMAKE_CXX_COMPILER