• 嵌入式
• 硬件开发
• 开发工具
• 调试器

本篇技术指南以 stlink 官方 doc/release.md 为骨架，系统讲解开源 STM32 编程工具集 stlink 的完整版本发布（Release）流程：如何维护三份变更日志、如何更新语义化版本号.version、如何按develop → master分支模型打标签，以及如何用 CPack 与交叉编译脚本生成.deb/.rpm/.zip二进制包并上传发布。读完本文，你将掌握一套可直接照做的发布操作清单，并理解每一步背后对应的构建系统实现（CMake / CPack / Makefile），为在本地复现或维护 stlink 版本发布提供依据。

发布流程总览：九步清单

根据 doc/release.md，一次完整的 stlink 发布需要依次完成以下 9 个步骤：

下面逐一对每个步骤展开，并结合仓库源码说明其底层机制与注意事项。

第一步：更新三份变更日志

发布时变更日志不是只改一处，而是三个（甚至四个）文件保持同步：

1. CHANGELOG.md（仓库根目录）：面向用户的主变更日志。以当前仓库为例，文件开头即按版本组织，例如# v1.8.1之下依次包含Release date、Updated system requirements（C 标准、cmake、libusb、libgtk 的最低版本要求）、Features:与Updates & changes:等小节，每个条目标注对应的 PR 或 commit 编号，见 CHANGELOG.md。
2. cmake/packaging/deb/changelog：Debian 包专用 changelog，采用 Debian 包格式，形如：

   stlink (1.8.0) unstable; urgency=medium * Release v1.8.0 -- Nightwalker-87 <stlink-org> Thu, 01 Feb 2024 00:00:00 +0100

   该文件在打包时通过CPACK_DEBIAN_PACKAGE_CONTROL_EXTRA注入进.deb包，见 cmake/packaging/deb/changelog 与 cmake/modules/cpack_config.cmake。

3. cmake/packaging/rpm/changelog：RPM 包专用 changelog，通过CPACK_RPM_CHANGELOG_FILE注入.rpm包，见 cmake/packaging/rpm/changelog 与 cmake/modules/cpack_config.cmake。
4. （可选）debian/changelog：仓库还维护了一套独立的 Debian 源包打包目录，其中同样有 debian/changelog 与 debian/rules，供 Debian 发行版级打包使用；发布时若同步维护源包版本也需一并更新。

版本号一致性约定：在 cmake/modules/cpack_config.cmake 中可以看到注释明确写道“每当 upstream 版本号递增时，debian_revision 应从 1 重新开始”（CPACK_DEBIAN_PACKAGE_RELEASE "1"），RPM 侧同样使用CPACK_RPM_PACKAGE_RELEASE "1"。也就是说，包内的修订号按版本独立计数，发布新版时应重置为 1。

第二步：用语义化版本更新.version文件

.version文件位于仓库根目录，内容就是一行语义化版本号x.x.x（如1.8.1），它承担着“源码包兜底版本源”的职责。

构建系统如何读取版本

版本号由 cmake/modules/get_version.cmake 解析，逻辑分两条路径：

• Git 仓库路径（优先）：执行git describe --always --tag获取版本；若本地源码有未提交改动，会在版本后追加-dirty后缀；随后剥离标签开头的v（如v1.8.1→1.8.1），再用正则拆出PROJECT_VERSION_MAJOR/MINOR/PATCH。若存在.version文件且与 git 版本不一致，会打印Rewrite .../.version with ...!提示；若.version不存在则会自动写入。
• 无 Git 兜底路径：当git未找到、.git目录不存在（如从源码压缩包构建）或git describe失败时，直接从.version文件读取版本字符串；若该文件也不存在，则FATAL_ERROR终止构建。

这说明发布时务必保证 git tag 与.version文件内容一致，否则构建系统会检测到不一致并给出重写提示。

版本号如何进入程序

版本宏在构建期由 inc/version.h.in 模板生成到头文件inc/version.h，其中的@PROJECT_VERSION@、@PROJECT_VERSION_MAJOR@等占位符会被替换为实际版本。同时 CMakeLists.txt 用PROJECT_VERSION_MAJOR.MINOR.PATCH设置共享库stlink-shared的SOVERSION与VERSION属性，因此版本号同时决定了libstlink.so的 soname 版本。换句话说，版本号的准确性直接关系到库的 ABI 版本标识。

第三步：更新 README 中的提交徽章

发布时还需将 README.md 中的“commits”徽章更新为新的语义化版本号x.x.x。这一步属于面向用户的信息同步——徽章通常显示当前发布版本的提交计数或发布状态，保证 README 首页展示的版本与本次发布一致。

第四步：更新安全策略 SECURITY.md

发布后需同步 SECURITY.md 的“Supported Versions”表格，将刚发布的版本标记为受支持（:white_check_mark:），并将旧版本标记为不再支持（:x:）。

以仓库现状为例，该表格的维护方式如下（当前develop与1.8.1受支持，1.8.0及更早版本不受支持）：

同时 SECURITY.md 注明：由于这是开发工具集，bug 修复只会应用到最新版本；发现漏洞应通过常规 bug report issue 报告。

第五步：将develop合并进master

stlink 采用经典的双分支发布模型：

• develop：日常开发集成分支，所有新功能、修复先合入这里；
• master：稳定发布分支，仅存放可发布的代码状态。

发布前需执行：

git checkout master git merge develop

合并完成后，master即代表本次要发布的代码快照。所有后续的标签与打包都基于该状态进行。

第六步：创建并推送 git 标签

在master上为发布版本打上语义化标签并推送：

git tag x.x.x git push origin master git push origin x.x.x

标签名必须与.version文件内容严格一致（如1.8.1，不带头字母v，因为 get_version.cmake 会显式剥离标签开头的v）。该标签会被git describe --always --tag捕获，进而驱动 CMake 自动推导PROJECT_VERSION——所以打标签的顺序最好在打包之前完成，确保包内版本正确。

第七步：生成二进制包（.rpm / .deb / .zip）

发布包由两条产出线构成：

7.1 原生平台打包：make package

仓库根目录 Makefile 将 CMake 目标封装为高层命令。make package等价于在build/Release目录中执行make package（见 Makefile），最终驱动 CPack 生成安装包：

make package

包产出的具体位置与格式由 cmake/modules/cpack_config.cmake 按平台分支决定：

• Debian/Ubuntu 上打包：CPACK_GENERATOR "DEB;RPM"（RPM 需要系统安装rpm包），即一次打包同时产出.deb与.rpm，输出目录为build/Release/dist。.deb包的依赖、维护者、建议安装包等信息在 cmake/modules/cpack_config.cmake 中定义（依赖libusb-1.0-0-dev (>= 1.0.24)、cmake (>= 3.19)等，Suggests为libgtk-3-dev, pandoc）；.deb还会附带 changelog、copyright、rules、postinst 四个 Debian 控制文件，见 cmake/modules/cpack_config.cmake。
• Windows 上打包：CPACK_GENERATOR "ZIP"，产出stlink-<版本>-win32.zip（或交叉编译时带TOOLCHAIN_PREFIX后缀的 zip），见 cmake/modules/cpack_config.cmake。
• 其他平台：不生成包。

7.2 Windows 交叉编译包：sh ./generate_binaries.sh

官方发布文档中第 7 步写作make package && sh ./generate_binaries.sh，注意仓库中的实际脚本名为gen_binaries_win.sh（位于仓库根目录），执行时以实际文件为准：

make package sh ./gen_binaries_win.sh

gen_binaries_win.sh 内部依次完成两项 MinGW 交叉编译并产出 Windows 的.zip包：

1. x86_64 目标：在build-mingw-64目录中调用cmake -DTOOLCHAIN_PREFIX=x86_64-w64-mingw32 -DCMAKE_TOOLCHAIN_FILE=../cmake/modules/set_toolchain.cmake -DCMAKE_SYSTEM_PROCESSOR="x86_64" -DCMAKE_C_FLAGS="-D_WIN32 -D_AMD64_" -DSTLINK_GENERATE_GUI=OFF ..，随后make package生成 zip 并拷贝到build/Release/dist；
2. i686 目标：在build-mingw-32目录中重复上述流程（TOOLCHAIN_PREFIX=i686-w64-mingw32，CMAKE_SYSTEM_PROCESSOR="i686"，CMAKE_C_FLAGS="-D_WIN32"）。

脚本中多处使用sudo cp拷贝产物，因此执行该脚本需要 sudo 权限；同时本机需已安装 MinGW 交叉编译工具链（mingw-w64、autotools-dev、libtool），详见 doc/compiling.md。最终所有包（.deb、.rpm与两个.zip）都会汇总到build/Release/dist目录。

需要说明的适用前提：按 doc/compiling.md 的说明，MSVC 编译环境下的包生成尚未实现/测试，本文所述make package的包生成流程适用于 Linux（Debian 系）与 MinGW 交叉编译场景。

第八步：上传包到 Release 页面

将build/Release/dist下生成的.rpm/.deb/.zip文件连同 CHANGELOG 摘要上传到项目的 GitHub Releases 页面，填写发布说明（通常包含新特性、修复与升级注意事项，可直接取自 CHANGELOG.md 对应版本小节）。发布说明中建议附上校验信息与目标平台说明，便于用户验证下载完整性。

第九步：将master合并回develop

发布完成后，将master上的发布提交（含标签、CHANGELOG 更新、.version与 SECURITY 更新等）合并回develop，使开发分支同步发布状态：

git checkout develop git merge master

这一步保证了后续开发始终基于“已发布版本 + 新改动”的基线，避免下一次发布时遗漏本次发布对版本文件与文档的改动。

发布前自检清单

综合全文，一次发布在动手前建议逐项核对：

结语

stlink 的发布流程看似九步，实则围绕两条主线：版本信息的一致性（.version、git tag、CHANGELOG、README 徽章、SECURITY 五者必须指向同一版本）与打包产物的可复现性（make package驱动 CPack 在 Linux 上同时产出.deb/.rpm，gen_binaries_win.sh通过 MinGW 交叉编译产出 32/64 位 Windows zip）。理解了 cmake/modules/get_version.cmake 的版本推导逻辑与 cmake/modules/cpack_config.cmake 的平台分支，就能在发布出现版本不符、包格式缺失等问题时快速定位根因。按照本文清单逐步执行，即可完成一次标准、可追溯的 stlink 版本发布。

• 嵌入式
• 硬件开发
• 开发工具
• 调试器