WeChatPad 内置 parallel-hashmap 的版本发布全流程:源码 Tag、Conan 与 vcpkg 包同步实战

原创2026-10-15 19:58:211,666 阅读
文章标签:移动开发原生移动

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)中执行:

  1. 先设置环境变量 VCPKG_ROOT(指向 vcpkg 仓库根目录);
  2. 执行 vcpkg install parallel-hashmap --triplet x64-windows,以 x64-windows 三元组实际安装一次,验证端口可用;
  3. 若安装时报校验和不匹配,需要在 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 依赖的项目同样有参考价值。仓库中该库的集成方式可以从三处源码确认:

  1. 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> 直接引用头文件。

  2. 实际使用:如第 1 节所述,dex_builder.cc 使用 phmap::flat_hash_map<TypeDescriptor, TypeDescriptor> 与 phmap::flat_hash_map<TypeDescriptor, std::string> 完成类型映射查找。

  3. 测试与示例:库自带完整的 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 依赖的版本管理机制,这份检查单都值得保留。

登录后查看全文
WeChatPad