工程构建综合复习：发布 Mesh::Core / Engineering Build Review: Releasing Mesh::Core

1. 用一个完整发布案例收束知识

学完 target、测试、ABI、链接和 CI 后，真正的检验是能否发布一个小而完整的库。这个案例假设你要发布 Mesh::Core v1.2，让旧消费者升级到新动态库时仍能运行。

2. 最简单心智模型

先定义公开承诺，再设计 target 和包。 先建立失败可见的门禁，再允许发布。 最后用旧消费者、新消费者和回滚路径证明版本能安全演进。

Mesh::Core source
  -> CMake target policy
  -> unit/integration/sanitizer/fuzz
  -> ABI baseline
  -> install package
  -> consumer smoke test
  -> release evidence ledger

3. 核心术语

贯穿案例：用同一个小库串起 target、测试、ABI、打包、发布和回滚，避免知识点彼此孤立。

target 设计：把公开头文件、私有实现、依赖传播和安装导出组织成清晰的构建边界。

质量门禁：案例发布前必须通过的检查集合，包括测试、sanitizer、ABI、consumer smoke 和包校验。

ABI baseline：上一版稳定发布留下的二进制契约记录，用来判断这次改动是否破坏兼容。

consumer test：站在使用者项目的角度安装并调用 Mesh::Core，验证包元数据和运行时依赖。

release checklist：发布前后逐项确认的清单，确保版本、制品、证据、回滚和诊断入口都准备好。

4. 机制展开

案例约束

Mesh::Core 是一个共享库，公开 C++ 头文件较小，但二进制兼容只承诺同一主版本内稳定。

库发布 Windows/MSVC x64 和 Linux/GCC x64 两个平台。

发布包必须包含头文件、库文件、CMake package config、调试符号、许可证、SBOM 和 evidence manifest。

任务分解

第一步整理 target：公共头、私有实现、依赖作用域和安装导出。

第二步建立质量门禁：单测、集成测试、ASan/UBSan、静态分析和 release smoke test。

第三步建立 ABI baseline 和 consumer project。

第四步发布制品并保留回滚证据。

验收方式

验收不是看文档写得完整，而是能在干净目录里安装包、编译 consumer、运行测试、检查 ABI 报告并定位 build id。

5. 最小示例

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

release-check/
  old-consumer/
    build-and-run-against-new-library.ps1
  new-consumer/
    CMakeLists.txt
    main.cpp
  evidence/
    abi-baseline.json
    artifact-sha256.txt
    test-report.xml
    rollback.md

6. 工程取舍

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

7. 常见错误

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

8. 调试与验证方法

定义公开承诺

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

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

建立干净环境

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

observe target 设计
  -> isolate 质量门禁
  -> run minimal proof
  -> store evidence

固定工具版本

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

observe 贯穿案例
  -> isolate target 设计
  -> run minimal proof
  -> store evidence

保存失败证据

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

observe release checklist
  -> isolate 贯穿案例
  -> run minimal proof
  -> store evidence

区分私有与公开

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

observe consumer test
  -> isolate release checklist
  -> run minimal proof
  -> store evidence

审查跨平台差异

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

observe ABI baseline
  -> isolate consumer test
  -> run minimal proof
  -> store evidence

限制全局状态

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

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

做升级测试

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

observe target 设计
  -> isolate 质量门禁
  -> run minimal proof
  -> store evidence

设置回滚入口

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

observe 贯穿案例
  -> isolate target 设计
  -> run minimal proof
  -> store evidence

写入 CI

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

observe release checklist
  -> isolate 贯穿案例
  -> run minimal proof
  -> store evidence

管理例外

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

observe consumer test
  -> isolate release checklist
  -> run minimal proof
  -> store evidence

保持证据总账

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

observe ABI baseline
  -> isolate consumer test
  -> run minimal proof
  -> store evidence

9. 本篇专属检查表

1. PUBLIC header review 已完成。
2. install tree consumer 能构建。
3. 旧消费者可替换新库运行。
4. ABI diff 已审查。
5. 回滚包和符号已归档。

检查点	通过标准	失败时优先看哪里
贯穿案例	有可重复命令、报告或 consumer 证明	target 属性、CI 日志、符号报告、包元数据
target 设计	有可重复命令、报告或 consumer 证明	target 属性、CI 日志、符号报告、包元数据
质量门禁	有可重复命令、报告或 consumer 证明	target 属性、CI 日志、符号报告、包元数据
ABI baseline	有可重复命令、报告或 consumer 证明	target 属性、CI 日志、符号报告、包元数据
consumer test	有可重复命令、报告或 consumer 证明	target 属性、CI 日志、符号报告、包元数据
release checklist	有可重复命令、报告或 consumer 证明	target 属性、CI 日志、符号报告、包元数据

10. 练习任务

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

12. 总结

《工程构建综合复习：发布 Mesh::Core / Engineering Build Review: Releasing Mesh::Core》的核心不是多记几个命令，而是把 贯穿案例、target 设计、质量门禁、ABI baseline、consumer test、release checklist 变成可审查、可复现、可回滚的工程证据。

返回 08 工程构建质量路线

深化问题 1：target 设计 怎样变成证据

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

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

rule: target 设计
owner: module maintainer
proof: command + report + artifact
failure: block merge or require documented exception

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

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

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

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

深化问题 3：ABI baseline 怎样变成证据

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

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

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

深化问题 4：consumer test 怎样变成证据

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

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

rule: consumer test
owner: module maintainer
proof: command + report + artifact
failure: block merge or require documented exception

深化问题 5：release checklist 怎样变成证据

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

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

rule: release checklist
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：target 设计 怎样变成证据

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

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

rule: target 设计
owner: module maintainer
proof: command + report + artifact
failure: block merge or require documented exception

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

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

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

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

深化问题 9：ABI baseline 怎样变成证据

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

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

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

深化问题 10：consumer test 怎样变成证据

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

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

rule: consumer test
owner: module maintainer
proof: command + report + artifact
failure: block merge or require documented exception

深化问题 11：release checklist 怎样变成证据

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

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

rule: release checklist
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：target 设计 怎样变成证据

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

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

rule: target 设计
owner: module maintainer
proof: command + report + artifact
failure: block merge or require documented exception

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

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

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

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

深化问题 15：ABI baseline 怎样变成证据

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

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

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

深化问题 16：consumer test 怎样变成证据

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

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

rule: consumer test
owner: module maintainer
proof: command + report + artifact
failure: block merge or require documented exception

深化问题 17：release checklist 怎样变成证据

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

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

rule: release checklist
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：target 设计 怎样变成证据

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

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

rule: target 设计
owner: module maintainer
proof: command + report + artifact
failure: block merge or require documented exception

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

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

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

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

深化问题 21：ABI baseline 怎样变成证据

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

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

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