WeChatPad 内置 parallel-hashmap 的版本发布全流程:源码 Tag、Conan 与 vcpkg 包同步实战
WeChatPad 内置 parallel-hashmap 的版本发布全流程:源码 Tag、Conan 与 vcpkg 包同步实战
本文以 WeChatPad 仓库内随 dex_builder 一起 vendored 的 parallel-hashmap 库为背景,完整讲解其维护者视角的版本发布流程:从修改
phmap_config.h版本号、打语义化 Tag,到同步发布 Conan 包与 vcpkg 端口。读完本文,你将掌握一次 parallel-hashmap 新版本从源码到三大分发渠道的完整发布清单,并能对照仓库源码理解版本号在构建系统中的真实作用。
1. 背景:这份发布文档对应的是哪个库
本文讲解的发布流程文档位于仓库的 vendored 第三方库目录:
该文档是 parallel-hashmap(header-only 的并行哈希表与 B-tree 容器库)的维护者发布检查单。虽然它被随项目源码一起带入仓库,但它面向的是上游库的新版本发布流程,而不是 WeChatPad 自身功能的开发流程。在 WeChatPad 中,这个库被 dex_builder(DEX 字节码生成器)用作基础数据结构:例如 dex_builder.cc 中通过 phmap::flat_hash_map 实现类型描述符拆箱映射与取值方法名映射,dex_builder.h 中直接 #include <parallel_hashmap/phmap.h>。
因此,理解这份发布文档,实际上就是在理解:上游每发布一个新版本时,源码、Conan、vcpkg 三条发布链路分别要做哪些事,这也能帮助下游集成者(如 WeChatPad)在升级 vendored 依赖时,知道版本号、校验和与 Tag 之间如何对应。
2. 发布前:版本号需要在三处保持同步
文档开头的清单非常明确地指出了源码发布的第一步工作——在发布一个新版本之前,版本号必须同步更新到两处源码位置:
2.1 更新 phmap_config.h 中的版本宏
- update version in phmap_config.h
即修改 parallel_hashmap/phmap_config.h 顶部的三个版本宏。以本仓库当前 vendored 的版本为例,实际内容为:
#define PHMAP_VERSION_MAJOR 1
#define PHMAP_VERSION_MINOR 3
#define PHMAP_VERSION_PATCH 11
也就是说,本仓库内置的 parallel-hashmap 当前版本为 1.3.11(文档正文中的 1.3.8 仅是发布当时的示例版本号,流程本身与具体版本无关)。发布新版本时,只需把这三个宏改成新版本号即可。
2.2 更新 CMakeLists.txt 顶部注释
- update version in comment on top of CMakeLists.txt
即 external/parallel_hashmap/CMakeLists.txt 顶部那段 FetchContent 使用示例中的 GIT_TAG v1.3.8 注释,需要与新版本保持一致:
include(FetchContent)
FetchContent_Declare(
parallel-hashmap
GIT_REPOSITORY https://github.com/greg7mdp/parallel-hashmap.git
GIT_TAG v1.3.8 # adjust tag/branch/commit as needed
)
FetchContent_MakeAvailable(parallel-hashmap)
...
include_directories(${parallel-hashmap_SOURCE_DIR})
这里给出了下游通过 CMake FetchContent 引用该库的标准方式。虽然文档只要求“更新顶部注释”,但从源码结构看,注释中的 Tag 同时也是下游消费者拷贝示例时的实际引用值,因此保持与真实发布 Tag 一致非常重要。
2.3 版本宏在构建系统中的真正作用
版本号不只写在注释里,它还参与了实际的 CMake 构建。仓库中的 cmake/DetectVersion.cmake 会在配置阶段读取 phmap_config.h 中三个版本宏,并拼装成完整的版本字符串:
file(READ "${CMAKE_CURRENT_SOURCE_DIR}/parallel_hashmap/phmap_config.h" _PHMAP_H_CONTENTS)
string(REGEX REPLACE ".*#define PHMAP_VERSION_MAJOR ([0-9]+).*" "\\1" DETECTED_PHMAP_VERSION_MAJOR "${_PHMAP_H_CONTENTS}")
string(REGEX REPLACE ".*#define PHMAP_VERSION_MINOR ([0-9]+).*" "\\1" DETECTED_PHMAP_VERSION_MINOR "${_PHMAP_H_CONTENTS}")
string(REGEX REPLACE ".*#define PHMAP_VERSION_PATCH ([0-9]+).*" "\\1" DETECTED_PHMAP_VERSION_PATCH "${_PHMAP_H_CONTENTS}")
set(DETECTED_PHMAP_VERSION "${DETECTED_PHMAP_VERSION_MAJOR}.${DETECTED_PHMAP_VERSION_MINOR}.${DETECTED_PHMAP_VERSION_PATCH}")
随后在 CMakeLists.txt 中被 project(phmap VERSION ${DETECTED_PHMAP_VERSION} LANGUAGES CXX) 使用。这意味着:如果发布时漏改 phmap_config.h 的版本宏,CMake 的 project 版本号就会与发布的 Tag 不一致。这就是文档把“更新版本宏”列为第一步的原因。
3. 源码发布:Git 提交、推送与 GitHub Release
文档列出的源码发布主流程为:
- git commit
- git push
- create the new release on github (tag `v1.3.8` - use semantic versioning)
- download the tar.gz from github, and use `sha256sum parallel-hashmap-1.3.8.tar.gz` on linux to get the sha256
3.1 提交与推送
在完成第 2 节的两处版本号修改后,执行常规的 git commit 与 git push 提交变更。这是所有后续包发布(Conan / vcpkg)的基础——因为包发布拉取的正是 GitHub 上的源码归档。
3.2 创建 GitHub Release(语义化版本 Tag)
发布时需要在 GitHub 上创建 Release,并使用**语义化版本(Semantic Versioning)**命名 Tag,例如 v1.3.8。语义化版本的核心约定是 主版本号.次版本号.修订号(MAJOR.MINOR.PATCH):
- MAJOR(主版本):不兼容的 API 变更;
- MINOR(次版本):向后兼容的功能新增;
- PATCH(修订号):向后兼容的问题修复。
Tag 前缀统一带 v(如 v1.3.8),这是该库一贯的 Tag 命名风格,也与第 2.2 节 CMake 注释中的 GIT_TAG v1.3.8 保持一致。
3.3 计算源码归档的 SHA-256 校验和
Release 创建后,从 GitHub 下载对应版本的 tar.gz 源码包,并在 Linux 上计算 SHA-256:
sha256sum parallel-hashmap-1.3.8.tar.gz
这一步产出的校验和是后续 Conan 与 vcpkg 配置文件中唯一可信的来源——两个包管理器都是通过"下载地址 + 校验和"来锁定源码包的完整性与安全性。
4. Conan 包发布流程
Conan 是 C/C++ 的包管理器,parallel-hashmap 通过 Conan 中心仓库(conan-center-index)分发。文档给出的流程分四步:
4.1 Fork 并准备分支
- fork and clone conan-center repo (or sync + git pull)
- git checkout master
- git checkout -b phmap_1.3.8
先 fork 并 clone conan-center-index 仓库(已有克隆则先同步再 git pull),确保基于最新的 master 创建发布分支,分支命名惯例为 phmap_<版本号>。
4.2 更新 Conan 配方文件
- update: recipes/parallel-hashmap/all/conandata.yml and recipes/parallel-hashmap/config.yml
需要修改两个文件:
| 文件 | 作用 |
|---|---|
recipes/parallel-hashmap/all/conandata.yml |
定义每个版本的源码下载地址与 SHA-256 校验和(即第 3.3 步算出的值) |
recipes/parallel-hashmap/config.yml |
登记新版本号,使其进入可解析的版本清单 |
4.3 本地验证:conan create
先升级 Conan 工具本身,再在配方目录中本地创建并验证包:
- sudo pip install conan -U
- cd recipes/parallel-hashmap/all
- conan create conanfile.py parallel-hashmap/1.3.8@ -pr:b=default -pr:h=default
对命令参数稍作拆解:
conan create conanfile.py parallel-hashmap/1.3.8@:基于conanfile.py在本地构建并生成版本为1.3.8的包,供后续上传使用;-pr:b=default:指定 build profile(构建环境) 为默认配置;-pr:h=default:指定 host profile(运行/目标环境) 为默认配置。
conan create 成功意味着配方文件、版本号与校验和全部正确,包可以在本地完整构建。这一步是合并到中心仓库前的本地自测关卡,能避免把坏配方合入中心仓库。
4.4 提交与 PR
- git diff
- git commit -am "[parallel-hashmap] Bump version to 1.3.8"
- git push origin phmap_1.3.8
- create PR like this
用 git diff 复查改动,提交信息遵循 [parallel-hashmap] Bump version to <版本号> 的规范格式,推送到远程分支后,向 conan-center-index 提交 Pull Request(参照仓库中既有版本的同类 PR 写法)。
5. vcpkg 包发布流程
vcpkg 是微软的 C/C++ 包管理器,parallel-hashmap 同样通过 vcpkg 的端口(port)分发。流程与 Conan 类似,但命令与文件不同:
5.1 Fork 并准备分支
- fork and clone vcpkg repo (or sync + git pull)
- git checkout -b phmap_1.3.8
同样基于最新代码创建 phmap_1.3.8 发布分支。
5.2 更新 vcpkg 端口文件
- update ports/parallel-hashmap/portfile.cmake and ports/parallel-hashmap/vcpkg.json
两个文件的分工为:
| 文件 | 作用 |
|---|---|
ports/parallel-hashmap/portfile.cmake |
定义如何下载、解压、安装该库,其中包含下载源的 SHA-512 校验和(与 Conan 的 SHA-256 不同,vcpkg 使用 SHA-512) |
ports/parallel-hashmap/vcpkg.json |
声明端口元数据与版本号,vcpkg 的版本解析以此为准 |
5.3 在 Windows 上验证安装
- set VCPKG_ROOT=
- vcpkg install parallel-hashmap --triplet x64-windows
- # update sha in portfile.cmake - run `sha512sum parallel-hashmap-1.3.8.tar.gz` on linux
文档明确要求这一组操作在 Windows 的非 cygwin 控制台(即原生 cmd / PowerShell)中执行:
- 先设置环境变量
VCPKG_ROOT(指向 vcpkg 仓库根目录); - 执行
vcpkg install parallel-hashmap --triplet x64-windows,以x64-windows三元组实际安装一次,验证端口可用; - 若安装时报校验和不匹配,需要在 Linux 上对源码包执行
sha512sum parallel-hashmap-1.3.8.tar.gz重新计算 SHA-512,并回填到portfile.cmake。
注意:vcpkg 端口使用 SHA-512(
sha512sum),而 Conan 配方使用 SHA-256(sha256sum),两种校验和算法不同,发布时不要混用。
5.4 更新版本索引并提交
- git diff
- git commit -am "[parallel-hashmap] Bump version to 1.3.8"
- vcpkg x-add-version --all --overwrite-version ## (or ./vcpkg.exe --no-dry-run upgrade )
- git diff -am "[parallel-hashmap] run x-add-version"
- git commit ...
- git push origin phmap_1.3.8
提交发布变更后,还需要运行:
vcpkg x-add-version --all --overwrite-version
该命令会为所有端口重新生成版本数据库索引(版本号、提交哈希等元数据写入 vcpkg 的版本注册文件),--overwrite-version 表示覆盖旧版本记录;文档同时给出备选方案 ./vcpkg.exe --no-dry-run upgrade。随后把索引变更单独提交(提交信息如 [parallel-hashmap] run x-add-version),再推送分支。注意:如果漏掉这一步,vcpkg 的版本解析将无法识别新版本。
6. 发布流程全景图与核对清单
综合源码、Conan、vcpkg 三条链路,一次完整发布的总流程为:
修改 phmap_config.h 版本宏
修改 CMakeLists.txt 顶部注释
git commit → git push
创建 GitHub Release(Tag 使用语义化版本,如 v1.3.8)
下载 tar.gz,用 sha256sum 计算 SHA-256
│
├── Conan 链路:
│ fork conan-center-index → 分支 phmap_x.y.z
│ → 更新 conandata.yml(下载地址 + SHA-256)与 config.yml(版本登记)
│ → pip install conan -U
│ → conan create conanfile.py parallel-hashmap/x.y.z@ -pr:b=default -pr:h=default
│ → git diff → commit → push → 提交 PR
│
└── vcpkg 链路:
fork vcpkg → 分支 phmap_x.y.z
→ 更新 portfile.cmake(SHA-512)与 vcpkg.json(版本号)
→ Windows 原生控制台:set VCPKG_ROOT → vcpkg install --triplet x64-windows
→ sha512sum 回填校验和
→ git commit → vcpkg x-add-version --all --overwrite-version
→ 提交索引变更 → push
发布核对清单:
| 检查项 | 关键命令 / 文件 | 易错点 |
|---|---|---|
| 版本宏同步 | phmap_config.h 中 MAJOR/MINOR/PATCH |
漏改会导致 CMake project() 版本号与 Tag 不一致 |
| CMake 注释同步 | CMakeLists.txt 顶部 FetchContent 示例 |
示例 Tag 即下游拷贝值 |
| Release Tag | 语义化版本,前缀 v |
分支名、Tag、包版本号三者必须一致 |
| 源码校验和 | sha256sum <归档> |
必须基于 Release 的实际归档计算 |
| Conan 配方 | conandata.yml + config.yml |
使用 SHA-256 |
| Conan 自测 | conan create ... -pr:b=default -pr:h=default |
双 profile 缺一不可 |
| vcpkg 端口 | portfile.cmake + vcpkg.json |
使用 SHA-512 |
| vcpkg 索引 | vcpkg x-add-version --all --overwrite-version |
漏跑则新版本无法被解析 |
7. 从下游角度看这份文档:升级 vendored 依赖时看什么
发布文档对 WeChatPad 这类把 parallel-hashmap 作为 vendored 依赖的项目同样有参考价值。仓库中该库的集成方式可以从三处源码确认:
-
CMake 构建集成:app/src/main/jni/CMakeLists.txt 通过
add_subdirectory(dex_builder)引入 dex_builder,而 dex_builder 的 CMakeLists.txt 以子目录方式包含 external 下的 parallel-hashmap;NDK 构建则见 Android.mk,其LOCAL_C_INCLUDES指向include目录,源码中通过#include <parallel_hashmap/phmap.h>直接引用头文件。 -
实际使用:如第 1 节所述,dex_builder.cc 使用
phmap::flat_hash_map<TypeDescriptor, TypeDescriptor>与phmap::flat_hash_map<TypeDescriptor, std::string>完成类型映射查找。 -
测试与示例:库自带完整的 tests(如
flat_hash_map_test.cc、parallel_flat_hash_map_test.cc)与 examples(如basic.cc、emplace.cc),上游每次发版前都会随 CMake 的PHMAP_BUILD_TESTS开关(见 CMakeLists.txt)跑一遍回归。
当你在自己的项目中升级 vendored 的 parallel-hashmap 时,建议对照本流程检查三件事:新版本 Tag 是否语义化、conandata.yml/portfile.cmake 中的校验和是否与新归档一致、版本宏是否与新版本号匹配。这三项正是发布文档要求维护者反复确认的关卡,也是下游避免引入损坏或错误版本的关键防线。
8. 结语
这份发布文档虽然篇幅不长,却完整覆盖了一个开源库发布时最容易被忽略的环节:版本号、Tag、校验和、包管理器配方之间的强一致性。通过对照仓库源码,我们可以看到版本宏如何被 DetectVersion.cmake 读取并注入 CMake 的 project() 版本号,也能看清 Conan 与 vcpkg 在校验和算法(SHA-256 vs SHA-512)和发布流程上的差异。无论是想为 parallel-hashmap 贡献新版本,还是仅仅想深入理解 vendored 依赖的版本管理机制,这份检查单都值得保留。