企业官网建设流程全解析

BLAKE3 发版全流程实战：以 mold 仓库内 vendored blake3 为例的版本发布检查清单

【免费下载链接】moldmold: A Modern Linker 🦠项目地址: https://gitcode.com/GitHub_Trending/mo/mold

导读

本文以 BLAKE3 项目官方发布的版本发布检查清单（third-party/blake3/tools/release.md）为主线，结合当前 mold 仓库中 vendored 的 BLAKE3 源码，系统讲解一个同时维护 Rust crate、命令行工具b3sum与 C 库的项目该如何完成一次规范的版本发布。读完本文，你将掌握从依赖审查、三处版本号同步、Cargo.lock重建、CLI 帮助文本更新，到提交打标签与cargo publish发布的完整操作序列，并理解每一步在源码中的具体落点。

说明：mold 仓库将 BLAKE3 作为第三方组件随源码分发（位于 third-party/blake3），本文所述发布流程针对该 vendored 组件本身，仓库当前内容对应的版本为 1.8.5。

发布检查清单全景

release.md 将一次完整发布拆解为 16 个步骤，按阶段可归纳为四类：

下文按此顺序逐步展开，并结合仓库源码说明每个操作"改的是什么、为什么改、在哪个文件"。

第一步：发布前的依赖审查（cargo outdated -R）

清单的第一步是在仓库根目录和b3sum/子目录分别执行：

cargo outdated -R

• -R表示递归检查所有依赖（包括传递依赖）；
• 该命令需要安装 cargo-outdated 子命令，用于列出落后于最新版的依赖；
• 清单要求其输出"干净"（clean），即不要带着可升级的过期依赖发布，避免新版本刚发布就携带旧依赖。

在 b3sum/Cargo.toml 中可以看到b3sum的直接依赖包括anyhow、blake3、clap、hex、rayon-core、wild等，而根 Cargo.toml 则依赖arrayref、arrayvec、constant_time_eq、cfg-if等基础库。这些依赖的版本健康度是发布前需要确认的第一道关卡。

第二步：同步 Rust 侧的版本号（两个 Cargo.toml）

BLAKE3 的 Rust 部分由两个 package 组成，发布时需要同时修改它们的版本号：

1. 根 crate（即blake3哈希库本体），当前内容见 Cargo.toml：

[package] name = "blake3" version = "1.8.5" edition = "2024"

2. CLI 工具b3sum，见 b3sum/Cargo.toml：

[package] name = "b3sum" version = "1.8.5" edition = "2024"

清单特别强调：如果新版本使用了根 crate 的新特性，b3sum对blake3的依赖版本也要同步上调。当前写法是：

[dependencies] blake3 = { version = "1.8", path = "..", features = ["mmap", "rayon"] }

其中version = "1.8"是 crates.io 上的版本约束，path = ".."是本地开发时指向根目录的路径；mmap与rayon特性分别启用内存映射 IO 与多线程哈希能力。发布前需确认这个版本约束能覆盖将要发布的新版本号。

顺带了解根 crate 的特性矩阵

修改根 Cargo.toml 版本号时，可以顺带核对特性是否完整。该 crate 通过 feature 开关控制实现与依赖：

• std（默认）：启用std::io相关 trait 与运行时 CPU 特性检测；
• neon：启用 ARM NEON 实现（使用 C intrinsics，需要 C 编译器）；
• wasm32_simd：启用 Wasm SIMD 实现；
• rayon：启用多线程哈希方法update_rayon/update_mmap_rayon；
• mmap：启用update_mmap等内存映射辅助方法；
• zeroize、traits-preview、serde：分别对应内存清零、RustCrypto trait、序列化支持；
• pure、prefer_intrinsics、no_sse2等：仅供测试与基准使用的不稳定特性，用于模拟不同硬件 SIMD 环境。

第三步：删除并重建 b3sum/Cargo.lock

清单要求：

# 删除 b3sum/Cargo.lock rm b3sum/Cargo.lock # 用任意构建动作重新生成 cargo build # 或 cargo check / cargo test 等

由于b3sum是一个独立的二进制 crate（有自己的Cargo.lock，见 b3sum/Cargo.lock），版本号提升后，锁文件中记录的依赖版本与 package 版本会出现不一致。删除后重建，可以确保：

• 锁文件反映最新的依赖解析结果；
• 发布到 crates.io 的包携带的Cargo.lock与源码树一致（对二进制 crate 而言锁文件会被打包发布）。

重建后应检查锁文件 diff，确认只发生了预期的版本变化，而不是引入了意外的依赖升级。

第四步：同步 CLI 帮助文本（b3sum/README.md）

b3sum的 README 内嵌了一段-h帮助输出（见 b3sum/README.md）。发布时如果 CLI 参数有任何增删改，需要把最新的b3sum --help输出粘贴回去，保证文档与实现一致。

当前 README 中的帮助文本对应 b3sum/src/main.rs 中基于clapderive 定义的实际参数：

Usage: b3sum [OPTIONS] [FILE]... Arguments: [FILE]... Files to hash, or checkfiles to check Options: --keyed 使用 keyed 模式，从 stdin 读取 32 字节密钥 --derive-key <CONTEXT> 使用密钥派生模式，指定上下文字符串 -l, --length <LEN> 输出字节数（hex 编码前），默认 32 --seek <SEEK> 输出起始字节偏移（hex 编码前），默认 0 --num-threads <NUM> 使用的最大线程数 --no-mmap 禁用内存映射 --no-names 输出中省略文件名 --raw 向 stdout 输出原始字节而非 hex --tag 输出 BSD 风格校验和：BLAKE3 ([FILE]) = [HASH] -c, --check 从 [FILE] 读取 BLAKE3 校验和并核对 --quiet 核对通过时不打印 OK -h, --help 打印帮助（更多见 '--help'） -V, --version 打印版本

在源码中，--check的校验逻辑相当严谨：main.rs中专门实现了parse_check_line、check_one_line、check_one_checkfile等函数，对校验文件的格式、非法字符（如 Windows 路径反斜杠）都有防御性处理，并有配套的单元测试（见 b3sum/src/unit_tests.rs）。关于--check的语义，仓库还提供了专门文档 b3sum/what_does_check_do.md。

第五步：同步 C 库的版本号（blake3.h 与 CMakeLists.txt）

BLAKE3 的 C 实现与 Rust 实现共用同一套版本语义，因此 C 侧也有两处必须同步修改：

1. 头文件宏BLAKE3_VERSION_STRING

c/blake3.h 中的宏是 C API 版本信息的唯一来源：

#define BLAKE3_VERSION_STRING "1.8.5"

该宏被 c/blake3.c 中的blake3_version()函数返回：

const char *blake3_version(void) { return BLAKE3_VERSION_STRING; }

也就是说，C 用户可以通过blake3_version()在运行时查询版本，因此发布时必须同步更新这个宏，否则运行时报出的版本号与 crates.io 上的版本不一致。

2. CMake 工程版本号

c/CMakeLists.txt 中通过project()声明了库的版本：

project(libblake3 VERSION 1.8.5 )

这个版本随后被用于共享库的SOVERSION与 pkg-config 文件（libblake3.pc.in中的Version字段），同样需要在发布时同步递增。

顺带一提，c/blake3.h 还定义了若干与发布无关但值得留意的 ABI 常量：BLAKE3_KEY_LEN 32、BLAKE3_OUT_LEN 32、BLAKE3_BLOCK_LEN 64、BLAKE3_CHUNK_LEN 1024、BLAKE3_MAX_DEPTH 54——这些是算法层面的固定参数，不会随版本变化。

第六步：提交、推送与 CI 验证

版本号与文档同步完毕后：

# 1. 提交版本提升，并在提交信息中附带 changelog / 变更说明 git commit -m "Bump version to X.Y.Z - <变更说明 1> - <变更说明 2>" # 2. 推送到远程 git push # 3. 等待 CI 全绿

清单要求"版本提升提交附带变更说明"（change notes），因此该提交通常就是 changelog 的载体，之后 CI 需要对新的版本组合做完整构建与测试验证。

第七步：打标签（git tag）

CI 通过后，为版本提升提交打上带版本号的标签并推送：

git tag X.Y.Z # 例如 git tag 1.8.5 git push --tags

这里的标签名与 crates.io 上的发布版本保持一致，便于用户把某个 crates.io 版本对应回源码树的精确状态。

第八步：发布到 crates.io（两次 cargo publish）

发布阶段在根目录与b3sum/目录各执行一次：

# 1. 先发布根 crate：blake3 cargo publish # 在仓库根目录执行 # 2. 再发布 b3sum（它依赖刚发布的 blake3） cargo publish # 在 b3sum/ 目录执行

顺序是硬性的：b3sum以blake3为依赖，根 crate 必须先发布成功，b3sum才能以正确的版本约束被发布。这也是为什么清单把"根目录 publish"排在"b3sum/publish"之前。

仓库中的验证与落点

在本 mold 仓库中，可以对照以下文件逐一验证发布清单的每个落点：

需要说明的是：mold 仓库以只读方式 vendored 了该组件，本文描述的发布操作适用于 BLAKE3 上游仓库或你自行 fork 的维护分支；在 mold 仓库内，这些文件主要用于随源码分发与构建（如b3sum在测试脚本中作为校验工具使用）。

小结：一次发布的完整命令序列

将全部步骤浓缩为可直接执行的顺序：

# 1. 发布前审查 cargo outdated -R # 根目录 cd b3sum && cargo outdated -R # b3sum 子目录 # 2. 同步版本号 # - 根 Cargo.toml # - b3sum/Cargo.toml（含对 blake3 的依赖版本） # - c/blake3.h 的 BLAKE3_VERSION_STRING # - c/CMakeLists.txt 的 project(... VERSION ...) # 3. 重建锁文件 rm b3sum/Cargo.lock && cargo build # 4. 同步 CLI 帮助文本到 b3sum/README.md # 5. 提交、推送、验证 CI git commit -m "Bump version to X.Y.Z ..." git push # 6. 打标签 git tag X.Y.Z && git push --tags # 7. 发布 cargo publish # 根目录 cd b3sum && cargo publish # b3sum 子目录

这套流程的核心思想是：版本信息分散在 Rust 与 C 两套构建体系、四个文件中，发布的关键不在于"执行 cargo publish"，而在于发布前把所有版本线索同步一致——这正是tools/release.md这份检查清单存在的意义，也是任何同时维护多语言绑定与 CLI 的哈希库项目可以复用的发布范式。

【免费下载链接】moldmold: A Modern Linker 🦠项目地址: https://gitcode.com/GitHub_Trending/mo/mold