CMAKE_TOOLCHAIN_FILE是交叉编译强制入口，必须显式设置CMAKE_SYSTEM_NAME=Linux或Generic以触发交叉模式，否则CMAKE_CROSSCOMPILING为FALSE，find_package等行为回退宿主机导致链接失败。
CMAKE_TOOLCHAIN_FILE 不是可选配置，而是交叉编译的强制入口 —— 漏设或设错，CMAKE_CROSSCOMPILING 就不会变成 TRUE，所有依赖目标平台的行为（比如 find_package()、externalproject_add()）都会悄悄回退到宿主机，构建看似成功，实则链接失败或运行崩溃。
为什么 CMAKE_SYSTEM_NAME 必须显式设为 Linux 或 Generic
这不是“建议”，而是 CMake 的触发开关。只有当 CMAKE_SYSTEM_NAME 被设为非当前主机系统名（如 Linux、Generic、Windows）时，CMake 才会激活交叉编译模式，并自动把 CMAKE_CROSSCOMPILING 设为 TRUE。设成 ARM 或留空，CMake 仍按本地编译逻辑走。
-
CMAKE_SYSTEM_NAME Linux：用于带内核的嵌入式 Linux（如树莓派、i.MX6） -
CMAKE_SYSTEM_NAME Generic：用于裸机（bare-metal），如 STM32、nRF52，此时必须加set(CMAKE_TRY_COMPILE_TARGET_TYPE STATIC_LIBRARY)，否则 CMake 会尝试链接可执行文件并失败 - 别写
CMAKE_SYSTEM_NAME ARM—— ARM 不是操作系统，CMake 不认识这个值，CMAKE_CROSSCOMPILING保持FALSE
CMAKE_SYSROOT 和 CMAKE_FIND_ROOT_PATH 到底谁管什么
CMAKE_SYSROOT 是给编译器用的（传给 gcc --sysroot=），只影响头文件和库的默认搜索路径；CMAKE_FIND_ROOT_PATH 是给 CMake 自己的 find_*() 系列命令用的，决定 find_library()、find_path() 在哪找。
- 两者通常指向同一目录（如
/usr/arm-linux-gnueabihf），但语义不同，缺一不可 -
CMAKE_SYSROOT必须存在且含usr/include和usr/lib，否则#include <stdio.h>都会报错 -
CMAKE_FIND_ROOT_PATH可设多个路径，例如：set(CMAKE_FIND_ROOT_PATH /opt/sysroot /home/user/custom-libs) - 如果只设了
CMAKE_SYSROOT没设CMAKE_FIND_ROOT_PATH，find_package(Threads)会去宿主机找libpthread.so，导致链接时符号缺失
CMAKE_FIND_ROOT_PATH_MODE_* 这三个开关怎么配才不翻车
它们控制 CMake 查找行为的“隔离强度”。配错一个，就可能混用宿主机工具或库，而错误往往延迟到链接或运行时才暴露。
CMake 4.3.2 Windows x86_64 历史版本安装包，适合旧项目兼容、构建环境回退、CMakeLists.txt 迁移验证、Visual Studio/Ninja/Makefile 生成器测试和 C/C++ 项目维护。
-
CMAKE_FIND_ROOT_PATH_MODE_PROGRAM NEVER：宿主机程序（如git、python、flex）绝不能从目标路径找 —— 否则find_program(PYTHON3 python3)可能返回目标 sysroot 里的假 Python -
CMAKE_FIND_ROOT_PATH_MODE_LIBRARY ONLY：链接阶段只允许在CMAKE_FIND_ROOT_PATH下找库 —— 这是硬性要求，设成BOTH或漏设，find_library(crypto)会优先返回宿主机的libcrypto.so，ABI 不兼容直接报undefined reference to `OPENSSL_sk_num' -
CMAKE_FIND_ROOT_PATH_MODE_INCLUDE ONLY：头文件也只认目标路径 —— 防止stdlib.h来自宿主机，导致size_t定义宽度错误
验证 toolchain 文件是否真正生效的三行命令
别等 make 报错才排查。在生成 build 目录前，用这三行快速确认关键变量：
cmake -DCMAKE_TOOLCHAIN_FILE=arm-linux-gnueabihf.cmake -GNinja -S . -B build-test cmake -LH -N build-test | grep -E "(CMAKE_SYSTEM|CMAKE_CXX_COMPILER|CMAKE_SYSROOT|CMAKE_CROSSCOMPILING)" cmake -LA -N build-test | grep CMAKE_FIND_ROOT_PATH_MODE
输出中必须看到：CMAKE_SYSTEM_NAME:STRING=Linux、CMAKE_SYSTEM_PROCESSOR:STRING=arm、CMAKE_CROSSCOMPILING:BOOL=ON、CMAKE_SYSROOT:PATH=/path/to/sysroot、以及四个 CMAKE_FIND_ROOT_PATH_MODE_* 均为预期值。任何一项不符，说明 toolchain 文件未被加载或内部有语法错误（比如 set() 括号不匹配）。
最容易被忽略的是：toolchain 文件里不能出现任何 project() 或 add_executable() —— 它只是配置脚本，不是项目文件；另外，路径中若含空格或中文，必须用双引号包裹，否则 CMake 解析失败且无提示。
