CMake：同一份源码为什么会生成两套完全不同的构建

CMake 如何把 target 模型变成可执行构建图把源码 target、usage requirements、toolchain、preset、generator 和安装导出串成一条可审查的生成链。高清原图

同一份 C++ 源码，在开发机生成 Visual Studio solution，在 Linux CI 生成 Ninja 文件，在交叉编译机又指向 sysroot 和另一套编译器。三处都运行 cmake，产物却可能在 ABI、编译选项和依赖来源上完全不同。问题不在于 CMake “编译得不一致”，而在于它根本不是编译器：它读取项目模型和环境输入，再为选定的 generator 生成底层构建系统。

把这层关系看清，排障顺序才不会颠倒。编译器报语法错要看编译命令；Ninja 报依赖边缺失要看生成图；CMake 配置阶段找不到库，则要追查 package、toolchain、cache 和搜索路径。把所有失败都归为“CMake 问题”，只会不断删除目录碰运气。

先确认命令、编译器和生成器来自哪里

CMake 官方下载页提供 Windows、macOS、Linux 的安装包与摘要；Linux 发行版仓库也常提供 CMake，但版本可能落后。先根据项目 cmake_minimum_required() 和团队支持矩阵选择版本，再检查实际入口：

Get-Command cmake | Format-List Source
cmake --version
cmake --help

command -v cmake
cmake --version
cmake --help

cmake --help 的 Generators 区域会列出当前平台可用的 generator。看到 Ninja 不等于 Ninja 已安装，还要单独验证：

ninja --version
cc --version
c++ --version

Windows 使用 MSVC 时，应在 Developer PowerShell 或已正确初始化的构建环境中确认：

where.exe cl
cl
cmake --help

安装来源、系统要求或摘要有疑问时，从 CMake 官方下载页核对。项目升级前应再查看对应系列的 CMake Release Notes，尤其关注 policy、generator 和命令行为变化。不要把教程中的长期版本号写进团队基线，仓库应通过最低版本、preset 和 CI 镜像表达真实约束。

用一个可删除工程跑通三阶段

先创建如下目录：

cmake-lab/
├─ CMakeLists.txt
├─ CMakePresets.json
├─ include/
│  └─ greeting.h
├─ src/
│  ├─ greeting.cpp
│  └─ main.cpp
└─ tests/
   └─ greeting_test.cpp

头文件声明一个最小接口：

// include/greeting.h
#pragma once
#include <string>

std::string greeting();

// src/greeting.cpp
#include "greeting.h"

std::string greeting() {
  return "cmake-model-ok";
}

// src/main.cpp
#include "greeting.h"
#include <iostream>

int main() {
  std::cout << greeting() << '\n';
}

// tests/greeting_test.cpp
#include "greeting.h"

int main() {
  return greeting() == "cmake-model-ok" ? 0 : 1;
}

根目录的构建描述只围绕 target 组织：

cmake_minimum_required(VERSION 3.25)
project(cmake_lab VERSION 1.0.0 LANGUAGES CXX)

include(GNUInstallDirs)
include(CTest)

add_library(greeting src/greeting.cpp)
add_library(Lab::greeting ALIAS greeting)
target_compile_features(greeting PUBLIC cxx_std_17)
target_include_directories(greeting
  PUBLIC
    $<BUILD_INTERFACE:${CMAKE_CURRENT_SOURCE_DIR}/include>
    $<INSTALL_INTERFACE:${CMAKE_INSTALL_INCLUDEDIR}>
)

add_executable(cmake-lab src/main.cpp)
target_link_libraries(cmake-lab PRIVATE Lab::greeting)

if(BUILD_TESTING)
  add_executable(greeting-test tests/greeting_test.cpp)
  target_link_libraries(greeting-test PRIVATE Lab::greeting)
  add_test(NAME greeting.contract COMMAND greeting-test)
endif()

install(TARGETS greeting cmake-lab
  EXPORT LabTargets
  RUNTIME DESTINATION ${CMAKE_INSTALL_BINDIR}
  LIBRARY DESTINATION ${CMAKE_INSTALL_LIBDIR}
  ARCHIVE DESTINATION ${CMAKE_INSTALL_LIBDIR}
  INCLUDES DESTINATION ${CMAKE_INSTALL_INCLUDEDIR}
)
install(DIRECTORY include/ DESTINATION ${CMAKE_INSTALL_INCLUDEDIR})
install(EXPORT LabTargets
  NAMESPACE Lab::
  DESTINATION ${CMAKE_INSTALL_LIBDIR}/cmake/Lab
)

先显式指定独立 build tree：

cmake -S . -B build -G Ninja -DCMAKE_BUILD_TYPE=Debug
cmake --build build --parallel
ctest --test-dir build --output-on-failure
cmake --install build --prefix staging

这四条命令分别完成配置与生成、执行底层构建、运行测试和安装到 staging。预期结果是程序输出 cmake-model-ok，CTest 报告测试通过，staging 中出现头文件、库和可执行文件。源码目录不应出现对象文件、cache 或生成后的 Ninja 文件。

如果使用 Visual Studio、Xcode 或 Ninja Multi-Config 这类多配置 generator，构建类型不应在配置阶段用 CMAKE_BUILD_TYPE 选择，而是在构建和测试阶段指定：

cmake -S . -B build -G "Ninja Multi-Config"
cmake --build build --config Debug --parallel
ctest --test-dir build -C Debug --output-on-failure
cmake --install build --config Debug --prefix staging

单配置与多配置混淆，是“明明选了 Release 却运行 Debug 产物”的常见根因。判断时先执行 cmake -S . -B build -L 查看 cache，再检查底层构建命令和产物目录，而不是凭目录名猜配置。

Configure、Generate、Build 是三个不同现场

cmake -S . -B build 先执行 configure：读取 CMakeLists.txt、探测编译器、执行 find_package()、计算 target 和 cache。随后 generate 把模型写成 Ninja、Makefiles、Visual Studio solution 或 Xcode project。cmake --build build 才调用底层构建工具执行编译、链接和自定义命令。

这条链路给出一套实用的归因方法：

Could NOT find ... 出现在 configure，先查 package config、搜索路径和 toolchain。ninja: error 或 Make 的 target 错误出现在执行层，先看生成图和依赖边。undefined reference、LNK2019 出现在链接层，先检查 target 传播、库顺序、ABI 和实际链接命令。

程序启动后崩溃属于运行时现场，还要检查动态库搜索路径和配置文件。

Target 才是可维护的工程边界

旧工程常用全局命令修改目录状态：

include_directories(include)
add_definitions(-DUSE_FAST_MODE)
link_libraries(example)

这些设置会隐式影响后续 target，规模变大后很难回答某个编译选项从哪里传来。现代 CMake 应把 include directory、compile definition、compile feature 和 link dependency 附着到 target：

add_library(protocol src/protocol.cpp)
target_compile_features(protocol PUBLIC cxx_std_20)
target_include_directories(protocol PUBLIC include)
target_compile_definitions(protocol PRIVATE PROTOCOL_BUILDING_LIBRARY)
target_link_libraries(protocol PRIVATE Threads::Threads)

PRIVATE 只影响当前 target，INTERFACE 只形成消费者要求，PUBLIC 同时影响自身和消费者。它们不是可见性修饰符，而是构建 usage requirements 的传播方向。

例如头文件暴露 std::span，消费者编译时也需要 C++20，因此 cxx_std_20 应为 PUBLIC。实现文件内部使用线程库且头文件不暴露相关类型时，链接依赖通常为 PRIVATE。错误地把所有内容写成 PUBLIC 会污染整个依赖图；全部写成 PRIVATE 又会让消费者缺少 include path、宏或传递链接库。

排查传播结果时，先打开详细构建输出：

cmake --build build --verbose

然后核对失败 target 的真实编译和链接命令。不要只读 CMakeLists.txt 猜测，因为 generator expression、导入 target 和 toolchain 都可能改变最终参数。

Preset 把团队约定变成可执行入口

命令行里散落 -D 参数，会迅速产生“每个人都能构建，但谁也复现不了别人”的局面。CMakePresets.json 适合提交共享 generator、binary directory、cache variable 和 workflow 入口；CMakeUserPresets.json 适合个人本地覆盖，通常不入库。

{
  "version": 6,
  "cmakeMinimumRequired": {
    "major": 3,
    "minor": 25,
    "patch": 0
  },
  "configurePresets": [
    {
      "name": "base",
      "hidden": true,
      "generator": "Ninja",
      "binaryDir": "${sourceDir}/out/build/${presetName}",
      "cacheVariables": {
        "CMAKE_EXPORT_COMPILE_COMMANDS": true,
        "BUILD_TESTING": true
      }
    },
    {
      "name": "dev-debug",
      "inherits": "base",
      "cacheVariables": {
        "CMAKE_BUILD_TYPE": "Debug"
      }
    }
  ],
  "buildPresets": [
    {
      "name": "dev-debug",
      "configurePreset": "dev-debug",
      "jobs": 8
    }
  ],
  "testPresets": [
    {
      "name": "dev-debug",
      "configurePreset": "dev-debug",
      "output": { "outputOnFailure": true }
    }
  ]
}

使用时先列出可见 preset，再执行同名入口：

cmake --list-presets
cmake --preset dev-debug
cmake --build --preset dev-debug
ctest --preset dev-debug

Preset schema 与可用字段随 CMake 演进，遇到 schema version、include 或 workflow 行为问题时查 CMake Presets 手册。仓库最低 CMake 版本必须能理解选定 schema；不能只在最新开发机上通过。

Toolchain 文件描述目标平台，不是个人环境脚本

交叉编译不能只设置 CMAKE_C_COMPILER。目标系统、处理器、sysroot、编译器、查找根和必要初始化选项要形成可审查的 toolchain 文件：

set(CMAKE_SYSTEM_NAME Linux)
set(CMAKE_SYSTEM_PROCESSOR aarch64)

set(CMAKE_SYSROOT "/opt/sdk/sysroot")
set(CMAKE_C_COMPILER "/opt/sdk/bin/aarch64-linux-gnu-gcc")
set(CMAKE_CXX_COMPILER "/opt/sdk/bin/aarch64-linux-gnu-g++")

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)

调用时在首次 configure 前注入：

cmake -S . -B out/aarch64 \
  -G Ninja \
  -DCMAKE_TOOLCHAIN_FILE=cmake/toolchains/aarch64-linux.cmake

编译器和 toolchain 一旦写入 CMakeCache.txt，直接更换路径后继续复用 build tree 风险很高。稳妥做法是新建对应 build directory，或删除已确认可再生的旧 build tree 后重新 configure。

toolchain 文件不应包含开发者用户目录、长期 token 或企业内网密码。SDK 路径可由受控环境变量、preset 或 CI 镜像提供；凭证由构建环境的秘密注入机制提供。需要理解 toolchain 何时加载、哪些变量可用时，查 cmake-toolchains 手册。

find_package() 成功不等于找对了依赖

依赖发现通常有 Module mode 与 Config mode。前者由 Find<Package>.cmake 查找，后者读取依赖方安装的 <Package>Config.cmake。现代依赖最好提供带 namespace 的 imported target：

find_package(OpenSSL REQUIRED COMPONENTS SSL Crypto)
target_link_libraries(gateway PRIVATE OpenSSL::SSL OpenSSL::Crypto)

只看到 “found” 还不够，要检查版本、架构、Debug/Release 变体、静态/动态类型和实际路径。诊断时可启用：

cmake -S . -B build --debug-find
cmake -S . -B build -DCMAKE_FIND_DEBUG_MODE=ON

输出可能暴露内部目录，分享前需脱敏。不要把依赖目录硬编码成个人绝对路径，也不要为了越过证书错误关闭 TLS。企业代理、私有制品源和 CA 应在包管理器、网络层或受控环境中配置，CMake 只消费经过批准的依赖入口。

搜索顺序、registry、Config mode 和 Module mode 发生冲突时，查 find_package() 官方说明，再结合 --debug-find 判断实际命中的文件。

安装和导出决定下游能否正确消费

“本仓库能链接”只是第一关。一个可复用库还要把头文件、二进制和 target usage requirements 安装并导出。前面的 install(EXPORT ...) 会生成 target 文件；完整 package 通常还需生成 LabConfig.cmake 与版本文件，让下游能够：

find_package(Lab CONFIG REQUIRED)
target_link_libraries(consumer PRIVATE Lab::greeting)

安装验证应在全新目录建立消费工程，使用 staging prefix 查找，不要继续借用源码树：

cmake --install build --prefix staging
cmake -S consumer -B consumer-build \
  -DCMAKE_PREFIX_PATH="${PWD}/staging"
cmake --build consumer-build

绝对安装路径会破坏可搬迁性。安装规则、component、prefix 和 export 细节有疑问时查 install() 官方说明。二进制包发布、制品库部署和签名属于制品治理链路；这里的关键是先生成可被下游正确消费的安装树。

CTest 让构建和验证共用同一模型

启用 include(CTest) 后，BUILD_TESTING 控制测试 target。测试不应只靠开发者从 IDE 手点：

ctest --test-dir build --show-only=json-v1
ctest --test-dir build --output-on-failure
ctest --test-dir build --repeat until-pass:2

最后一条只适合识别偶发失败，不能作为长期掩盖 flaky test 的方案。多配置 generator 要加 -C Debug 或使用 test preset。需要按 label、fixture、resource 或并行策略组织测试时，从 CTest 手册核对当前行为。

增量构建失真时按输入链排查

改了头文件却没有重编译

先运行详细构建并检查生成器记录的依赖。若使用自定义代码生成器，确认 add_custom_command(OUTPUT ...) 声明了真实输出和 DEPENDS，必要时设置 BYPRODUCTS。不要把生成步骤塞进永远执行的 target，也不要靠手工 touch 文件修复依赖图。

切换编译器后出现奇怪 ABI 错误

检查 CMakeCache.txt 中编译器、sysroot、generator 和构建类型。切换工具链应使用新 build tree。只删对象文件而保留旧 cache，容易把探测结果和新编译器混合。

find_package() 在本机成功、CI 失败

比较 CMAKE_PREFIX_PATH、toolchain、package manager 集成文件、环境变量和 --debug-find 结果。本机系统目录中偶然存在的开发包不是仓库依赖契约。空镜像恢复失败时，应补齐依赖声明或批准的制品来源。

链接到错误架构或错误配置的库

打开 verbose 输出，检查真实库路径和 linker 命令；再确认 imported target 是否提供按配置映射。不要用一个全局 link_directories() 把多个架构和配置目录同时放进搜索路径。

修改 CMakeLists 后没有触发正确重生成

先运行 cmake --build build --verbose，观察 generator 是否重新调用 CMake。若生成文件被手改、时间戳异常或 generator 规则失效，删除可再生 build tree 后重新 configure，并把差异归因到生成器输入，而不是保留手工补丁。

CI 要保存配置证据，不只保存编译日志

权威流水线应从空 build tree 开始，用仓库 preset 运行 configure、build、test 和 install staging：

cmake --version
cmake --preset ci-release
cmake --build --preset ci-release --parallel
ctest --preset ci-release
cmake --install out/build/ci-release --prefix out/staging

证据至少包括 CMake、generator、编译器和 linker 版本，preset 名称，非敏感 cache 摘要，测试结果，安装树清单与产物摘要。完整 cache、环境变量和 --debug-find 输出可能包含内网路径或用户名，应按需脱敏。

缓存要区分三层：下载依赖缓存、编译器缓存、CMake build tree。跨 runner 复用完整 build tree 通常比重建更危险，因为 cache 保存绝对路径、编译器身份和平台探测结果。可共享的优先是可校验下载缓存和具备正确 key 的编译缓存；CMake 配置本身应能快速、确定地重建。

升级与迁移要同时保留新旧生成链

升级 CMake、generator 或 toolchain 时，先记录旧链路：

cmake --version
cmake -S . -B out/baseline --preset release
cmake --build out/baseline --verbose
ctest --test-dir out/baseline --output-on-failure

新版本使用全新 build tree，比较测试、安装树、公开符号、包大小和关键性能。CMake policy 警告不能通过长期忽略解决；应查明 policy 影响，在 cmake_minimum_required() 和局部兼容策略中明确迁移。

从全局变量迁移到 target model 时，可按库边界逐步改造：先建立 imported/alias target，再迁移 include、definition、compile option 和 link dependency，最后删除全局目录状态。回滚时恢复 CMakeLists、preset、toolchain 和 CI 镜像的同一基线，并使用干净 build tree；只降级 cmake 可执行文件可能无法恢复旧行为。

Cache 会把一次探测固化成长期错觉

编译器路径、依赖位置、feature test 和用户选项都可能进入 CMakeCache.txt。判断标准是：换机器、换编译器或换 SDK 后，空 build tree 能否重建同一结果。不能时，说明环境输入没有进入 preset、toolchain 或依赖契约。

Generator 是架构输入，不只是速度开关

Ninja、Make、Visual Studio 和 Xcode 在单/多配置、并行、IDE 元数据和命令行行为上不同。团队要规定受支持组合，并在代表性平台测试。开发机自由切换 generator 可以，但不得共用同一 build directory。

PUBLIC 滥用会形成隐形耦合

过度传播 include path、宏和库，会让任意下游偶然依赖传递细节。定期审查 exported targets 和消费者最小工程；删除某个直接依赖后仍能编译，不一定是好事，可能只是从别处泄漏进来。

私有依赖的路径和凭证属于不同边界

package 路径可进入受控 preset 或 toolchain，凭证不能进入仓库、cache、编译命令和产物。CI 使用短期最小权限凭证；调试日志上传前检查 URL、用户名、内部目录和证书信息。

交叉编译成功不等于目标机可运行

编译阶段只能证明工具链生成了产物。还要检查目标架构、动态依赖、sysroot 版本、运行时 ABI 和目标设备测试。try_run() 在交叉环境中的处理要明确，不能把宿主机运行结果当成目标机证据。

可重建安装树比源码树成功更有价值

发布前在空目录消费 staging 安装结果，能暴露缺失头文件、错误 namespace、绝对路径和未导出依赖。只在同一源码树里构建测试，无法证明下游消费契约成立。

CMake、generator、编译器、SDK 与 linker 的来源和支持组合可查询。configure、generate、build、test、install 五个阶段能分别定位失败。源码树与 build tree 分离，不提交 cache 和生成产物。

target usage requirements 使用 PRIVATE、PUBLIC、INTERFACE 表达真实传播。共享配置进入 CMakePresets.json，个人覆盖不污染仓库。交叉编译输入进入 toolchain，换工具链时使用新 build tree。

find_package() 命中的版本、架构、配置和真实路径可解释。安装导出能被空白消费工程通过 find_package() 使用。CTest 在本机和 CI 使用同一 preset 与配置运行。

CI 从空 build tree 重建，并保存非敏感配置证据和产物摘要。代理、CA、私有源和凭证没有通过绝对路径或 URL 泄漏进仓库与日志。CMake、generator 或 toolchain 升级使用独立目录并具备整链回滚方案。

现场变化时从对应入口取证

配置、target、generator expression 或命令语义不清时，从 CMake Documentation进入对应版本手册；最低版本与 policy 行为变化应结合仓库 cmake_minimum_required() 和 Policy 手册判断。

Preset 解析失败时查 cmake-presets(7)，交叉编译偏离预期时查 cmake-toolchains(7)，依赖发现错误时查 find_package()。每次都把官方语义与 cmake --version、实际命令、cache 和 verbose 构建输出对照，才能定位当前工程真正采用的行为。