CMake 构建：目标、依赖与可搬移包

目标图、阶段与缓存

先知道头文件、翻译单元和链接的区别。本节对照P2Report 的 CMakeLists.txt 与 CMakePresets.json阅读目标图和缓存，未运行构建。

专题入口：C++ 大型构建模型：目标图、阶段与缓存 · C++ 构建依赖：PUBLIC、私有头与可搬移包 · C++ 完整构建实践：库、CLI、测试与安装后消费 · C++ 构建排错：头文件、包发现、配置与规模

C++大型构建教学采用什么版本

C++大型构建教学采用什么版本：本课程固定 CMake 3.28 与 C++20 的教学语义，Presets 使用 schema 8，选 Ninja 单配置生成器。核对日期为2026-10-17；采用已发布文档作为教学基准，不代表当前最新版本或受支持平台已经验证。读者应预先准备 Ninja、编译器、标准库和 SDK，本轮没有安装或探测它们。

Windows 原生假设已初始化的 MSVC 开发者 PowerShell；Linux 假设 GCC/Clang 与配套标准库；macOS 假设 AppleClang 与 SDK。每次记录编译器、架构、运行库与 CMake 版本才能讨论二进制兼容；同是 C++20 不保证不同 ABI 的静态库可以互链。先读RAII基础，再按本系列进入目标依赖与完整工程。

CMake配置生成构建安装各做什么

CMake配置生成构建安装各做什么：配置执行 CMakeLists 并建立目标与属性；生成把目标图翻译为 Ninja 或 IDE 的构建规则；构建由后端驱动预处理、编译和链接；安装把已构建产物与声明的包元数据复制到前缀。配置/生成常由一次 cmake 调用完成，但它们与编译仍是不同阶段。

先判断错误发生在哪个阶段：find_package 找不到包通常在配置阶段；头文件找不到在编译；未定义符号在链接；安装目录里缺 Config 在安装规则或前缀选择。不能看到 cmake 配置成功就宣称 C++ 程序正确。本轮连配置都未执行，只人工核对目标与源文件契约。

构建不是仅把所有 cpp 拼成一个命令。库先编成自己的对象/归档，CLI 和测试分别链接库；改变库的实现会重编相关对象并重新链接依赖产物，改变公共头可能触及所有包含它的翻译单元。

大型CMake工程为什么围绕target组织

大型CMake工程为什么围绕target组织：target 是依赖图的节点，连接产物与用法要求；一个库拥有自己的源、头目录、编译特性和依赖。目录只是存放文件，不是传播范围的可靠边界。全局 include_directories 或 CMAKE_CXX_FLAGS 容易让本不相关的目标意外可编译，掩盖缺失依赖。

本例用 p2_report 表示可链接静态库，p2_options 是无产物的 INTERFACE 目标，用于共享 C++20 约束。P2::report/P2::options 是构建树 ALIAS；ALIAS 本身不能直接安装，实际目标通过 EXPORT_NAME 导出同名的 imported target。CLI 与测试只链接 P2::report，不手工重复它的 include 目录。

多模块工程可让每个子目录定义少量清晰目标，以 target_link_libraries 表达图，避免所有模块链接一个汇总“万能库”。不要为演示规模人为拆出十几个库；边界应由公共 API、复用关系与独立维护需求决定。

CMakePresets怎样隔离Debug和Release缓存

CMakePresets怎样隔离Debug和Release缓存：本例 binaryDir 为 out/${presetName}，debug/release 分别设置 CMAKE_BUILD_TYPE，从而隔离 CMakeCache.txt、对象与产物。隐藏 base 只共享 Ninja 和 BUILD_TESTING，不能直接作为可执行 preset；同名 build/test preset 显式指向对应 configurePreset。

Presets 固定可共享的项目选择，不应提交个人编译器绝对路径。用户机器设置放 CMakeUserPresets.json，并加入忽略规则。换生成器、架构或工具链时使用新构建目录；仅修改环境变量未必改变缓存中的编译器。缓存不是依赖锁文件，也不等于可复现的完整工具链环境。

单配置生成器在配置时选构建类型；Visual Studio 或 Ninja Multi-Config 在构建时选 --config。不能把两种命令拼在一起并假定同一输出目录。本例只提供单配置 preset；若要添加多配置方案，需一起修改 build/test configuration、安装 --config 与输出路径。

练习与自检

解释为何在同一个 out/debug 中从 Ninja 切到 Visual Studio 会造成缓存冲突；为第三种工具链提出目录命名方式。

参考答案与判断依据

生成器、编译器与 ABI 都参与构建树身份。保留已有目录，另用 out/msvc-debug 或 out/clang-debug 配置；目录名是约定，真正证据仍包括 preset 与缓存中的实际工具链。不通过删改旧缓存掩盖未知环境。

一手资料与验证边界

2026-10-17核对 CMake 3.28 Presets、导入导出指南、PackageConfigHelpers。版本固定用于教学，不作最新版本承诺。没有运行编译器、CMake配置/生成/构建/安装或CTest。

PUBLIC、私有头与可搬移包

先理解前节 target 与构建阶段，再对照安装配置和独立 consumer追踪用法要求与包发现；未执行安装或消费验证。

专题入口：C++ 大型构建模型：目标图、阶段与缓存 · C++ 构建依赖：PUBLIC、私有头与可搬移包 · C++ 完整构建实践：库、CLI、测试与安装后消费 · C++ 构建排错：头文件、包发现、配置与规模

CMake的PUBLIC PRIVATE INTERFACE怎样选择

CMake的PUBLIC PRIVATE INTERFACE怎样选择：PRIVATE 只用于当前目标的编译需求；INTERFACE 只给消费者；PUBLIC 同时用于当前目标和消费者。判断依据是公共 API 是否要求消费者看到某项约束，而不是想“保险一点”就全部 PUBLIC。

p2_report 的公共头用 C++20 接口，因而 PUBLIC 链接 P2::options；options 的 cxx_std_20 是 INTERFACE 要求。src 和 generated 头目录 PRIVATE，不该泄漏进 CLI。CLI 自己无须向任何目标传播库依赖，所以 PRIVATE 链接 report。警告开关也是库自己的 PRIVATE 构建政策，不强加给第三方消费者。

静态库的 PRIVATE 链接依赖还有链接阶段传播细节：归档并没有把依赖库代码自动复制进去，CMake 可能为最终链接保留仅链接依赖。不能把 PRIVATE 解释为最终链接永远不需要它；外部依赖还要在安装包 Config 中用 find_dependency 恢复相应目标。本例没有第三方链接依赖，避免把这个边界藏起来。

公共头与生成头为什么分开目录

公共头与生成头为什么分开目录：include/p2/report.hpp 是 API，src/detail.hpp 是实现，version.hpp 由 configure_file 生成在构建树。BUILD_INTERFACE 为源码构建提供公共头位置，INSTALL_INTERFACE 只记录相对安装头目录，让 imported target 在新前缀下重新定位。

version() 返回指向静态字符串字面量的 string_view，因此返回后仍有效；configure_file 只替换项目版本，不在公共 API 中暴露生成头。消费者不应知道 generated 目录，更不应依赖私有 detail.hpp。若公共头自己 include 了生成头，则该生成头也是公共安装契约，需要显式安装并设置可搬移的 include 关系。

不要在 INSTALL_INTERFACE 填当前机器的绝对源码路径或另一个依赖的 include 路径；依赖应通过它自己的 imported target 提供。实践项目用 GNUInstallDirs 处理平台目录习惯，仍需在实际平台验证目录布局，而不是承诺任意定制安装路径都可搬移。

CMake怎样安装并导出静态库包

CMake怎样安装并导出静态库包：install(TARGETS ... EXPORT P2ReportTargets) 收集真实目标；install(EXPORT ...) 生成带 P2:: 命名空间的目标描述；公共头和静态归档必须同时安装。只有 Targets 文件还不等于 find_package 可发现的包，入口 Config 负责 include 它并检查组件。

configure_package_config_file 生成 P2ReportConfig.cmake，write_basic_package_version_file 生成版本兼容判断。项目1.0.0声明 SameMajorVersion，消费者请求1可接受同主版本且满足请求的版本；这只是包声明的兼容政策，不会分析 C++ ABI 是否真的兼容。作者仍需维护 API/ABI 或调整版本策略。

p2_options 被库的导出用法要求引用，必须一起进入 export 集。本例导出 options/report，CLI 安装到 bin 但不导出为库接口。静态库无需共享库导出宏；若改成 SHARED，还须重新处理 Windows 符号可见性、运行库搜索与 ABI，不能只改一个关键字就声称跨平台完成。

下游工程怎样用find_package消费安装包

下游工程怎样用find_package消费安装包：独立 consumer 用 find_package(P2Report 1 CONFIG REQUIRED)，再 PRIVATE 链接 P2::report。CMAKE_PREFIX_PATH 指向安装前缀，CMake 在常规子目录寻找 Config；P2Report_DIR 则直接指向 Config 所在目录，两者不能混成 include 路径。

消费者没有 add_subdirectory 上游，没有相对路径穿越到 ../include；这能暴露漏装头、未导出接口要求、绝对路径污染等缺陷。源码树内 CLI 编译成功并不能替代安装后消费验证。部署时应把整个前缀复制到另一位置再使用新前缀检查可搬移性；本轮没有实际安装或执行这个检查。

多个版本同时存在时，旧 P2Report_DIR 缓存可能让查找继续命中旧包。先看配置日志和缓存的实际 Config 位置；不要用手写 -I/-L 来“修复”目标传播。版本文件可拒绝不兼容版本，但无法把不同架构静态库转换成可用产物。

练习与自检

假设公共 report.hpp 改为 include 一个外部库头。说明 PUBLIC/PRIVATE 与 Config 应怎样调整。

参考答案与判断依据

外部库的 imported target 应成为 report 的 PUBLIC 依赖，因为消费者需要它的头和用法要求。安装 Config 需要 include(CMakeFindDependencyMacro) 并 find_dependency 对应包，然后才 include 自己的 Targets。不能把开发机外部 include 绝对路径写进安装接口。

一手资料与验证边界

2026-10-17核对 CMake 3.28 Presets、导入导出指南、PackageConfigHelpers。版本固定用于教学，不作最新版本承诺。没有运行编译器、CMake配置/生成/构建/安装或CTest。