C++ 工程构建质量、ABI 与发布证据路线 / C++ Build Quality, ABI, and Release Evidence Roadmap

1. 从工具命令到工程证据

工具链能把代码编成程序，但工程质量要求你持续证明：每个 target 的使用要求清楚，测试和分析覆盖关键风险，ABI 变化被识别，制品能被干净环境消费，发布后能诊断和回滚。

2. 最简单心智模型

11 模块回答“编译器、链接器、构建系统怎样工作”。 08 模块回答“团队怎样把这些工具变成可重复的工程制度”。 不要把一次本机成功当成工程证据；证据必须能在另一个环境复现。

source + dependencies + toolchain
        |
        v
target graph -> tests/analyzers -> ABI checks -> package artifacts
        |              |              |             |
        +--------------+--------------+-------------+
                       v
              release evidence ledger

3. 核心术语

工程证据：能被别人重复检查的事实，例如 CI 日志、测试报告、ABI diff、包清单、构建 manifest 和回滚记录。

质量门禁：在合并、打包或发布前必须通过的检查。它不应该只是“跑一下脚本”，还要明确失败归属、修复路径和是否允许豁免。

ABI 策略：团队对二进制兼容性的承诺，包括哪些接口稳定、哪些变化算破坏、如何做版本号和兼容测试。

发布制品：交给使用者或部署系统的最终产物，例如库文件、头文件、包元数据、调试符号和校验信息。

回滚能力：新版本出问题时，能明确找到上一个可用版本、对应依赖和恢复步骤，而不是临时重新编一个“差不多”的包。

消费者验证：用一个独立项目像真实用户一样安装、链接、运行你的包，用来发现发布者本机环境掩盖的问题。

4. 机制展开

本模块和 11 的边界

如果你还不知道头文件搜索、目标文件、动态库搜索路径、Make/Ninja/CMake 的层次，请先读 11。

本模块默认你已经理解工具链的大致流程，然后把注意力放到工程策略上：怎样组织 target，怎样设置质量门禁，怎样保存发布证据。

一个好工程不是靠 README 里一句“请用 Debug 编译”维持，而是让配置、CI、包和测试共同约束错误用法。

读完后应该能回答的问题

一个库的 PUBLIC include、编译特性和链接依赖为什么是发布接口的一部分？

为什么 ABI 兼容不能只看头文件 diff？

为什么 release artifact 需要 debug symbols、build id、SBOM、依赖锁和 consumer test？

为什么 CI 绿色不等于可发布，而可发布需要证据矩阵？

推荐阅读路线

先读 01，建立 target usage requirements 的工程视角。

再读 02，把 warning、单测、Sanitizer、fuzz、benchmark 放到各自位置。

随后读 03、04、05，理解包、符号、ABI 如何形成发布边界。

最后读 06、07，把 CI、制品、回滚和贯穿案例串起来。

5. 最小示例

下面的示例不是完整项目，而是为了把本篇概念落到可审查文本。阅读代码时关注它暴露了哪些边界，而不是照抄每个名字。

command or project layout goes here

6. 工程取舍

选择	收益	风险	需要的证据
只在本机验证	反馈最快	环境不可复现	仅适合草稿，不适合作为发布结论
CI 快速门禁	阻止常见错误	覆盖不完整	明确矩阵、日志和失败归属
完整发布门禁	证据最强	成本更高	制品、符号、SBOM、ABI 和回滚记录
最小消费者测试	最接近用户	需要维护样例	独立目录、安装包、运行输出

7. 常见错误

• 把“当前源码树能构建”误认为“安装包能被别人消费”。
• 把 PRIVATE 实现细节通过头文件、导出符号或包配置泄漏出去。
• 只保存最终二进制，不保存构建输入、依赖锁、调试符号和版本信息。
• 只在 Debug 测试，不在 Release 或发布配置里测试。
• 把 CI 缓存当成依赖管理，把绿色状态当成发布结论。
• 遇到链接或 ABI 问题时只改 flags，不留下能够复盘的符号证据。

8. 调试与验证方法

定义公开承诺

写清楚本库承诺源码兼容、二进制兼容、协议兼容还是仅内部使用。承诺越模糊，升级事故越难判责。

observe 消费者验证
  -> isolate 工程证据
  -> run minimal proof
  -> store evidence

建立干净环境

用全新 build directory 和最小 consumer project 验证，不依赖源码树中的 include 路径和本机缓存。

observe 回滚能力
  -> isolate 消费者验证
  -> run minimal proof
  -> store evidence

固定工具版本

记录编译器、CMake、Ninja、包管理器、系统镜像和关键 flags，避免把偶然环境当成规则。

observe 发布制品
  -> isolate 回滚能力
  -> run minimal proof
  -> store evidence

保存失败证据

失败日志、符号报告、测试输出和构建命令要能被别人复现，而不是只留一句“CI failed”。

observe ABI 策略
  -> isolate 发布制品
  -> run minimal proof
  -> store evidence

区分私有与公开

私有实现可以快速迭代；公开头、导出符号、包元数据和 ABI policy 必须谨慎变更。

observe 质量门禁
  -> isolate ABI 策略
  -> run minimal proof
  -> store evidence

审查跨平台差异

Windows 的 DLL/import lib/PDB 与 Linux 的 so/SONAME/RPATH/debug file 不同，不能用一个平台的经验套全部。

observe 工程证据
  -> isolate 质量门禁
  -> run minimal proof
  -> store evidence

限制全局状态

全局 include、全局 flags、隐式环境变量和手工 PATH 修改都会让构建不可解释。

observe 消费者验证
  -> isolate 工程证据
  -> run minimal proof
  -> store evidence

做升级测试

old consumer + new library、new consumer + package install 是比单纯编译源码更接近用户现场的测试。

observe 回滚能力
  -> isolate 消费者验证
  -> run minimal proof
  -> store evidence

设置回滚入口

发布前准备上一稳定制品、数据库或文件格式迁移策略、插件兼容说明和符号包。

observe 发布制品
  -> isolate 回滚能力
  -> run minimal proof
  -> store evidence

写入 CI

能自动检查的规则不要只写在文章里；把它变成 preset、脚本、workflow 或 release checklist。

observe ABI 策略
  -> isolate 发布制品
  -> run minimal proof
  -> store evidence

管理例外

允许临时豁免时必须记录原因、过期时间和补偿测试，否则门禁会慢慢失去意义。

observe 质量门禁
  -> isolate ABI 策略
  -> run minimal proof
  -> store evidence

保持证据总账

把构建输入、依赖锁、测试、ABI、性能、SBOM、签名和制品 hash 放在同一发布记录中。

observe 工程证据
  -> isolate 质量门禁
  -> run minimal proof
  -> store evidence

9. 本篇专属检查表

1. target 图是否能解释 include 和 link 来源。
2. 是否有干净消费者工程。
3. 是否保存 ABI baseline。
4. 是否保存 build id 和符号。
5. 是否能回滚到上一个兼容包。

检查点	通过标准	失败时优先看哪里
工程证据	有可重复命令、报告或 consumer 证明	target 属性、CI 日志、符号报告、包元数据
质量门禁	有可重复命令、报告或 consumer 证明	target 属性、CI 日志、符号报告、包元数据
ABI 策略	有可重复命令、报告或 consumer 证明	target 属性、CI 日志、符号报告、包元数据
发布制品	有可重复命令、报告或 consumer 证明	target 属性、CI 日志、符号报告、包元数据
回滚能力	有可重复命令、报告或 consumer 证明	target 属性、CI 日志、符号报告、包元数据
消费者验证	有可重复命令、报告或 consumer 证明	target 属性、CI 日志、符号报告、包元数据

10. 练习任务

• 建立一个只有一个库和一个 consumer 的最小工程，证明安装树可用。
• 故意破坏一个 PUBLIC/PRIVATE 作用域，观察消费者构建失败方式。
• 保存一次链接或 ABI 报告，并写下它能证明什么、不能证明什么。
• 把一个手工验证命令改成 CI 步骤，并让失败消息能指向具体文件或配置。
• 写一份 release evidence 小清单，列出制品、符号、依赖、测试和回滚入口。

12. 总结

《C++ 工程构建质量、ABI 与发布证据路线 / C++ Build Quality, ABI, and Release Evidence Roadmap》的核心不是多记几个命令，而是把 工程证据、质量门禁、ABI 策略、发布制品、回滚能力、消费者验证 变成可审查、可复现、可回滚的工程证据。

返回 08 工程构建质量路线

深化问题 1：质量门禁 怎样变成证据

围绕 质量门禁 写一个项目规则：谁可以修改，修改后跑什么命令，失败时保存哪些输出。

对应的工程动作是：用全新 build directory 和最小 consumer project 验证，不依赖源码树中的 include 路径和本机缓存。

rule: 质量门禁
owner: module maintainer
proof: command + report + artifact
failure: block merge or require documented exception

深化问题 2：ABI 策略 怎样变成证据

围绕 ABI 策略 写一个项目规则：谁可以修改，修改后跑什么命令，失败时保存哪些输出。

对应的工程动作是：记录编译器、CMake、Ninja、包管理器、系统镜像和关键 flags，避免把偶然环境当成规则。

rule: ABI 策略
owner: module maintainer
proof: command + report + artifact
failure: block merge or require documented exception

深化问题 3：发布制品 怎样变成证据

围绕 发布制品 写一个项目规则：谁可以修改，修改后跑什么命令，失败时保存哪些输出。

对应的工程动作是：失败日志、符号报告、测试输出和构建命令要能被别人复现，而不是只留一句“CI failed”。

rule: 发布制品
owner: module maintainer
proof: command + report + artifact
failure: block merge or require documented exception

深化问题 4：回滚能力 怎样变成证据

围绕 回滚能力 写一个项目规则：谁可以修改，修改后跑什么命令，失败时保存哪些输出。

对应的工程动作是：私有实现可以快速迭代；公开头、导出符号、包元数据和 ABI policy 必须谨慎变更。

rule: 回滚能力
owner: module maintainer
proof: command + report + artifact
failure: block merge or require documented exception

深化问题 5：消费者验证 怎样变成证据

围绕 消费者验证 写一个项目规则：谁可以修改，修改后跑什么命令，失败时保存哪些输出。

对应的工程动作是：Windows 的 DLL/import lib/PDB 与 Linux 的 so/SONAME/RPATH/debug file 不同，不能用一个平台的经验套全部。

rule: 消费者验证
owner: module maintainer
proof: command + report + artifact
failure: block merge or require documented exception

深化问题 6：工程证据 怎样变成证据

围绕 工程证据 写一个项目规则：谁可以修改，修改后跑什么命令，失败时保存哪些输出。

对应的工程动作是：全局 include、全局 flags、隐式环境变量和手工 PATH 修改都会让构建不可解释。

rule: 工程证据
owner: module maintainer
proof: command + report + artifact
failure: block merge or require documented exception

深化问题 7：质量门禁 怎样变成证据

围绕 质量门禁 写一个项目规则：谁可以修改，修改后跑什么命令，失败时保存哪些输出。

对应的工程动作是：old consumer + new library、new consumer + package install 是比单纯编译源码更接近用户现场的测试。

rule: 质量门禁
owner: module maintainer
proof: command + report + artifact
failure: block merge or require documented exception

深化问题 8：ABI 策略 怎样变成证据

围绕 ABI 策略 写一个项目规则：谁可以修改，修改后跑什么命令，失败时保存哪些输出。

对应的工程动作是：发布前准备上一稳定制品、数据库或文件格式迁移策略、插件兼容说明和符号包。

rule: ABI 策略
owner: module maintainer
proof: command + report + artifact
failure: block merge or require documented exception

深化问题 9：发布制品 怎样变成证据

围绕 发布制品 写一个项目规则：谁可以修改，修改后跑什么命令，失败时保存哪些输出。

对应的工程动作是：能自动检查的规则不要只写在文章里；把它变成 preset、脚本、workflow 或 release checklist。

rule: 发布制品
owner: module maintainer
proof: command + report + artifact
failure: block merge or require documented exception

深化问题 10：回滚能力 怎样变成证据

围绕 回滚能力 写一个项目规则：谁可以修改，修改后跑什么命令，失败时保存哪些输出。

对应的工程动作是：允许临时豁免时必须记录原因、过期时间和补偿测试，否则门禁会慢慢失去意义。

rule: 回滚能力
owner: module maintainer
proof: command + report + artifact
failure: block merge or require documented exception

深化问题 11：消费者验证 怎样变成证据

围绕 消费者验证 写一个项目规则：谁可以修改，修改后跑什么命令，失败时保存哪些输出。

对应的工程动作是：把构建输入、依赖锁、测试、ABI、性能、SBOM、签名和制品 hash 放在同一发布记录中。

rule: 消费者验证
owner: module maintainer
proof: command + report + artifact
failure: block merge or require documented exception

深化问题 12：工程证据 怎样变成证据

围绕 工程证据 写一个项目规则：谁可以修改，修改后跑什么命令，失败时保存哪些输出。

对应的工程动作是：写清楚本库承诺源码兼容、二进制兼容、协议兼容还是仅内部使用。承诺越模糊，升级事故越难判责。

rule: 工程证据
owner: module maintainer
proof: command + report + artifact
failure: block merge or require documented exception

深化问题 13：质量门禁 怎样变成证据

围绕 质量门禁 写一个项目规则：谁可以修改，修改后跑什么命令，失败时保存哪些输出。

对应的工程动作是：用全新 build directory 和最小 consumer project 验证，不依赖源码树中的 include 路径和本机缓存。

rule: 质量门禁
owner: module maintainer
proof: command + report + artifact
failure: block merge or require documented exception

深化问题 14：ABI 策略 怎样变成证据

围绕 ABI 策略 写一个项目规则：谁可以修改，修改后跑什么命令，失败时保存哪些输出。

对应的工程动作是：记录编译器、CMake、Ninja、包管理器、系统镜像和关键 flags，避免把偶然环境当成规则。

rule: ABI 策略
owner: module maintainer
proof: command + report + artifact
failure: block merge or require documented exception

深化问题 15：发布制品 怎样变成证据

围绕 发布制品 写一个项目规则：谁可以修改，修改后跑什么命令，失败时保存哪些输出。

对应的工程动作是：失败日志、符号报告、测试输出和构建命令要能被别人复现，而不是只留一句“CI failed”。

rule: 发布制品
owner: module maintainer
proof: command + report + artifact
failure: block merge or require documented exception

深化问题 16：回滚能力 怎样变成证据

围绕 回滚能力 写一个项目规则：谁可以修改，修改后跑什么命令，失败时保存哪些输出。

对应的工程动作是：私有实现可以快速迭代；公开头、导出符号、包元数据和 ABI policy 必须谨慎变更。

rule: 回滚能力
owner: module maintainer
proof: command + report + artifact
failure: block merge or require documented exception

深化问题 17：消费者验证 怎样变成证据

围绕 消费者验证 写一个项目规则：谁可以修改，修改后跑什么命令，失败时保存哪些输出。

对应的工程动作是：Windows 的 DLL/import lib/PDB 与 Linux 的 so/SONAME/RPATH/debug file 不同，不能用一个平台的经验套全部。

rule: 消费者验证
owner: module maintainer
proof: command + report + artifact
failure: block merge or require documented exception

深化问题 18：工程证据 怎样变成证据

围绕 工程证据 写一个项目规则：谁可以修改，修改后跑什么命令，失败时保存哪些输出。

对应的工程动作是：全局 include、全局 flags、隐式环境变量和手工 PATH 修改都会让构建不可解释。

rule: 工程证据
owner: module maintainer
proof: command + report + artifact
failure: block merge or require documented exception

深化问题 19：质量门禁 怎样变成证据

围绕 质量门禁 写一个项目规则：谁可以修改，修改后跑什么命令，失败时保存哪些输出。

对应的工程动作是：old consumer + new library、new consumer + package install 是比单纯编译源码更接近用户现场的测试。

rule: 质量门禁
owner: module maintainer
proof: command + report + artifact
failure: block merge or require documented exception

深化问题 20：ABI 策略 怎样变成证据

围绕 ABI 策略 写一个项目规则：谁可以修改，修改后跑什么命令，失败时保存哪些输出。

对应的工程动作是：发布前准备上一稳定制品、数据库或文件格式迁移策略、插件兼容说明和符号包。

rule: ABI 策略
owner: module maintainer
proof: command + report + artifact
failure: block merge or require documented exception

深化问题 21：发布制品 怎样变成证据

围绕 发布制品 写一个项目规则：谁可以修改，修改后跑什么命令，失败时保存哪些输出。

对应的工程动作是：能自动检查的规则不要只写在文章里；把它变成 preset、脚本、workflow 或 release checklist。

rule: 发布制品
owner: module maintainer
proof: command + report + artifact
failure: block merge or require documented exception