包、ABI 与性能证据总账 / Packaging, ABI, and Performance Evidence Ledger

1. 发布包必须带着证据一起交付

发布不是把 zip 上传到网盘。发布意味着你能证明这个包来自哪个 commit、用哪个工具链构建、依赖哪些库、ABI 相比上一版是否兼容、性能是否在预算内、出现故障时怎样定位。

2. 最简单心智模型

包是制品，证据总账是制品可信的原因。 ABI、性能和依赖供应链都要有基线和变更记录。消费者验证比发布者自测更能暴露安装路径、运行时依赖和包元数据问题。

text

commit/tag
  -> build manifest
  -> package artifact
  -> ABI report
  -> benchmark report
  -> symbols/build-id
  -> SBOM/provenance

3. 核心术语

包可安装：包在干净环境里能完成安装，并且头文件、库文件、配置文件和运行时依赖都落在约定位置。

ABI diff：比较两个版本导出的符号、类型布局和二进制契约，判断旧消费者是否还能加载新库。

性能基线：某个版本在固定环境、固定输入、固定方法下的性能记录，用来识别后续退化。

debug symbols：调试符号把地址映射回函数、文件和行号。发布时可以和二进制分离保存，但不能丢。

SBOM：软件物料清单，记录制品里包含或依赖了哪些组件、版本和许可证。

provenance：制品来源证明，回答它由哪个源码、哪个构建环境、哪个流水线步骤产生。

4. 机制展开

证据总账是什么

证据总账是一组可追溯文件，不是散落在 CI 日志里的截图。

它至少包含构建输入、工具版本、依赖锁、测试报告、ABI 报告、性能报告、制品校验和和回滚说明。

包可安装证据

在干净环境里安装包，然后用最小 consumer project 执行 find_package、编译、链接、运行。

这一步能发现 install/export、RPATH、DLL 复制、运行库和缺失依赖问题。

性能证据

性能基线应有输入规模、机器标签、编译选项、统计方式和阈值。

性能回归不是只看平均值，p95、内存峰值、启动时间和文件大小也可能是发布指标。

5. 最小示例

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

text

release-evidence/
  manifest.json
  artifacts/
    Mesh-1.2.0-windows-msvc-x64.zip
    Mesh-1.2.0-linux-gcc-x64.tar.gz
  reports/
    tests-junit.xml
    abi-diff.html
    benchmark.json
    sbom.spdx.json
  symbols/
    mesh_core.pdb
    libmesh_core.so.debug

6. 工程取舍

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

7. 常见错误

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

8. 调试与验证方法

定义公开承诺

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

text

observe 包可安装
  -> isolate ABI diff
  -> run minimal proof
  -> store evidence

建立干净环境

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

text

observe provenance
  -> isolate 包可安装
  -> run minimal proof
  -> store evidence

固定工具版本

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

text

observe SBOM
  -> isolate provenance
  -> run minimal proof
  -> store evidence

保存失败证据

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

text

observe debug symbols
  -> isolate SBOM
  -> run minimal proof
  -> store evidence

区分私有与公开

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

text

observe 性能基线
  -> isolate debug symbols
  -> run minimal proof
  -> store evidence

审查跨平台差异

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

text

observe ABI diff
  -> isolate 性能基线
  -> run minimal proof
  -> store evidence

限制全局状态

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

text

observe 包可安装
  -> isolate ABI diff
  -> run minimal proof
  -> store evidence

做升级测试

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

text

observe provenance
  -> isolate 包可安装
  -> run minimal proof
  -> store evidence

设置回滚入口

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

text

observe SBOM
  -> isolate provenance
  -> run minimal proof
  -> store evidence

写入 CI

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

text

observe debug symbols
  -> isolate SBOM
  -> run minimal proof
  -> store evidence

管理例外

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

text

observe 性能基线
  -> isolate debug symbols
  -> run minimal proof
  -> store evidence

保持证据总账

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

text

observe ABI diff
  -> isolate 性能基线
  -> run minimal proof
  -> store evidence

9. 本篇专属检查表

artifact 是否有 sha256。
ABI 报告是否对比上一稳定版。
benchmark 是否有阈值。
debug symbol 是否和 build id 对应。
SBOM 是否随包保存。

检查点	通过标准	失败时优先看哪里
包可安装	有可重复命令、报告或 consumer 证明	target 属性、CI 日志、符号报告、包元数据
ABI diff	有可重复命令、报告或 consumer 证明	target 属性、CI 日志、符号报告、包元数据
性能基线	有可重复命令、报告或 consumer 证明	target 属性、CI 日志、符号报告、包元数据
debug symbols	有可重复命令、报告或 consumer 证明	target 属性、CI 日志、符号报告、包元数据
SBOM	有可重复命令、报告或 consumer 证明	target 属性、CI 日志、符号报告、包元数据
provenance	有可重复命令、报告或 consumer 证明	target 属性、CI 日志、符号报告、包元数据

10. 练习任务

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

12. 总结

《包、ABI 与性能证据总账 / Packaging, ABI, and Performance Evidence Ledger》的核心不是多记几个命令，而是把 包可安装、ABI diff、性能基线、debug symbols、SBOM、provenance 变成可审查、可复现、可回滚的工程证据。

返回 08 工程构建质量路线

深化问题 1：ABI diff 怎样变成证据

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

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

text

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

深化问题 2：性能基线怎样变成证据

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

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

text

rule: 性能基线
owner: module maintainer
proof: command + report + artifact
failure: block merge or require documented exception

深化问题 3：debug symbols 怎样变成证据

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

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

text

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

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

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

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

text

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

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

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

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

text

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

深化问题 6：包可安装怎样变成证据

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

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

text

rule: 包可安装
owner: module maintainer
proof: command + report + artifact
failure: block merge or require documented exception

深化问题 7：ABI diff 怎样变成证据

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

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

text

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

深化问题 8：性能基线怎样变成证据

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

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

text

rule: 性能基线
owner: module maintainer
proof: command + report + artifact
failure: block merge or require documented exception

深化问题 9：debug symbols 怎样变成证据

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

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

text

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

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

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

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

text

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

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

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

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

text

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

深化问题 12：包可安装怎样变成证据

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

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

text

rule: 包可安装
owner: module maintainer
proof: command + report + artifact
failure: block merge or require documented exception

深化问题 13：ABI diff 怎样变成证据

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

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

text

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

深化问题 14：性能基线怎样变成证据

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

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

text

rule: 性能基线
owner: module maintainer
proof: command + report + artifact
failure: block merge or require documented exception

深化问题 15：debug symbols 怎样变成证据

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

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

text

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

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

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

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

text

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

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

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

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

text

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

深化问题 18：包可安装怎样变成证据

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

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

text

rule: 包可安装
owner: module maintainer
proof: command + report + artifact
failure: block merge or require documented exception

深化问题 19：ABI diff 怎样变成证据

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

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

text

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

深化问题 20：性能基线怎样变成证据

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

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

text

rule: 性能基线
owner: module maintainer
proof: command + report + artifact
failure: block merge or require documented exception

深化问题 21：debug symbols 怎样变成证据

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

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

text

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

包、ABI 与性能证据总账 / Packaging, ABI, and Performance Evidence Ledger ​

1. 发布包必须带着证据一起交付 ​

2. 最简单心智模型 ​

3. 核心术语 ​

4. 机制展开 ​

证据总账是什么 ​

包可安装证据 ​

性能证据 ​

5. 最小示例 ​

6. 工程取舍 ​

7. 常见错误 ​

8. 调试与验证方法 ​

定义公开承诺 ​

建立干净环境 ​

固定工具版本 ​

保存失败证据 ​

区分私有与公开 ​

审查跨平台差异 ​

限制全局状态 ​

做升级测试 ​

设置回滚入口 ​

写入 CI ​

管理例外 ​

保持证据总账 ​

9. 本篇专属检查表 ​

10. 练习任务 ​

12. 总结 ​

深化问题 1：ABI diff 怎样变成证据 ​

深化问题 2：性能基线 怎样变成证据 ​

深化问题 3：debug symbols 怎样变成证据 ​

深化问题 4：SBOM 怎样变成证据 ​

深化问题 5：provenance 怎样变成证据 ​

深化问题 6：包可安装 怎样变成证据 ​

深化问题 7：ABI diff 怎样变成证据 ​

深化问题 8：性能基线 怎样变成证据 ​

深化问题 9：debug symbols 怎样变成证据 ​

深化问题 10：SBOM 怎样变成证据 ​

深化问题 11：provenance 怎样变成证据 ​

深化问题 12：包可安装 怎样变成证据 ​

深化问题 13：ABI diff 怎样变成证据 ​

深化问题 14：性能基线 怎样变成证据 ​

深化问题 15：debug symbols 怎样变成证据 ​

深化问题 16：SBOM 怎样变成证据 ​

深化问题 17：provenance 怎样变成证据 ​

深化问题 18：包可安装 怎样变成证据 ​

深化问题 19：ABI diff 怎样变成证据 ​

深化问题 20：性能基线 怎样变成证据 ​

深化问题 21：debug symbols 怎样变成证据 ​

包、ABI 与性能证据总账 / Packaging, ABI, and Performance Evidence Ledger

1. 发布包必须带着证据一起交付

2. 最简单心智模型

3. 核心术语

4. 机制展开

证据总账是什么

包可安装证据

性能证据

5. 最小示例

6. 工程取舍

7. 常见错误

8. 调试与验证方法

定义公开承诺

建立干净环境

固定工具版本

保存失败证据

区分私有与公开

审查跨平台差异

限制全局状态

做升级测试

设置回滚入口

写入 CI

管理例外

保持证据总账

9. 本篇专属检查表

10. 练习任务

12. 总结

深化问题 1：ABI diff 怎样变成证据

深化问题 2：性能基线怎样变成证据

深化问题 3：debug symbols 怎样变成证据

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

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

深化问题 6：包可安装怎样变成证据

深化问题 7：ABI diff 怎样变成证据

深化问题 8：性能基线怎样变成证据

深化问题 9：debug symbols 怎样变成证据

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

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

深化问题 12：包可安装怎样变成证据

深化问题 13：ABI diff 怎样变成证据

深化问题 14：性能基线怎样变成证据

深化问题 15：debug symbols 怎样变成证据

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

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

深化问题 18：包可安装怎样变成证据

深化问题 19：ABI diff 怎样变成证据

深化问题 20：性能基线怎样变成证据

深化问题 21：debug symbols 怎样变成证据