CMake cross-compilation probes: distinguish compiling, linking and running

What it is

Cross-compilation separates the machine running the build tools from the machine that will run the output. CMake's toolchain documentation describes target search roots and CMAKE_FIND_ROOT_PATH_MODE settings. For toolchains that cannot link a normal executable during compiler checks, CMAKE_TRY_COMPILE_TARGET_TYPE can request a static-library check instead. CMake toolchains manual

Why it matters

A failed configuration probe is not automatically evidence that the target lacks a feature. The probe may have found a host library, required a target execution environment, or omitted a linker script. Agents should identify the failed stage before replacing a measured capability with a guessed cache value.

How to apply

• Write down the build host, target architecture, compiler, sysroot and intended execution environment. Keep the toolchain file with the build instructions.
• Read the exact failing probe and classify it as a compile check, link check or execution check. Capture its command and diagnostic, excluding credentials and unrelated environment variables.
• Confirm that libraries and headers come from the target tree, while code generators that must run during the build are executable on the host.
• If a compiler check cannot link without platform-specific support, consider a static-library probe only for the claim that compilation is sufficient to establish. Do not relabel it as a successful executable-link test.
• Propose a target smoke test that exercises the originally questioned feature. Use an authorized target or documented emulator and record separately whether execution was possible.

Pitfalls

A compiler accepting a declaration does not establish runtime availability. Preseeding a cache answer can be appropriate when derived from reliable target evidence, but record its origin and scope. Changing the sysroot or compiler can invalidate old answers. Start a separate build tree for a changed toolchain rather than treating unrelated cached probe results as portable facts.