C / C++ / 系统课时
为程序加入版本信息
为程序加入版本信息
发布后的二进制如果不能自报版本,排障时很难确认用户实际运行的是哪一次构建。本节把版本号只维护在 CMake 项目定义中,再通过生成头文件编译进 C 程序,并提供 --version 命令用于现场核对。
学习目标
- 使用 CMake 的项目版本作为唯一版本来源
- 用
configure_file()生成包含版本宏的头文件 - 编译并验证程序能够通过命令行输出版本号
用项目版本作为唯一来源
CMake 的 project(... VERSION ...) 会定义 PROJECT_VERSION、PROJECT_VERSION_MAJOR、PROJECT_VERSION_MINOR 等变量。把版本放在这里,可以避免 CMake 配置、C 源码和发布脚本各自维护一份号码。
下面的项目把版本设为 1.4.2,并在配置阶段生成 version.h。
cmake_minimum_required(VERSION 3.20)
project(versioned_app VERSION 1.4.2 LANGUAGES C)
file(MAKE_DIRECTORY "${CMAKE_CURRENT_BINARY_DIR}/generated")
configure_file(
"${CMAKE_CURRENT_SOURCE_DIR}/version.h.in"
"${CMAKE_CURRENT_BINARY_DIR}/generated/version.h"
@ONLY
)
add_executable(versioned_app main.c)
target_include_directories(versioned_app
PRIVATE
"${CMAKE_CURRENT_BINARY_DIR}/generated"
)version.h.in 是配置模板,不直接交给编译器。@ONLY 表示只替换 @VAR@ 形式的占位符,能避免模板中的其他 ${...} 文本被意外展开。
#ifndef VERSION_H
#define VERSION_H
#define APP_VERSION "@PROJECT_VERSION@"
#define APP_VERSION_MAJOR @PROJECT_VERSION_MAJOR@
#define APP_VERSION_MINOR @PROJECT_VERSION_MINOR@
#define APP_VERSION_PATCH @PROJECT_VERSION_PATCH@
#endif配置完成后,生成目录中的 version.h 会包含真正的数字和字符串。这个文件属于构建产物,通常不需要提交到版本库。
在程序中暴露版本命令
主程序只需要包含生成的头文件,并约定一个稳定的命令行入口。下面的实现接受 --version,其他参数则返回用法错误。
#include <stdio.h>
#include <string.h>
#include "version.h"
int main(int argc, char *argv[])
{
if (argc == 2 && strcmp(argv[1], "--version") == 0) {
printf("versioned_app %s\n", APP_VERSION);
return 0;
}
fprintf(stderr, "usage: %s --version\n", argv[0]);
return 2;
}在 Linux 或 macOS 的单配置生成器中,可以直接完成配置、编译和验证。
cmake -S . -B build -DCMAKE_BUILD_TYPE=Release
cmake --build build
./build/versioned_app --versionCMake 的配置与编译日志会随生成器和编译器不同而变化;关键验证结果是最后一条命令输出的版本号。
预期输出
versioned_app 1.4.2为什么生成头文件比手写宏可靠
如果直接在 main.c 里写 #define APP_VERSION "1.4.2",升级版本时就必须同时修改 CMake 和源码,漏改任意一处都会产生“包名是新版本、程序却自报旧版本”的冲突。生成头文件把版本流向固定为“CMake 项目版本 → 配置阶段生成头文件 → 编译进程序”,维护点只有一个。
configure_file() 在 CMake 配置阶段执行,因此修改 project() 中的版本后,需要重新运行 CMake 配置,再重新编译程序。只重新执行旧的二进制不会改变其中已经编译进去的字符串。
版本号的边界
project(VERSION ...) 适合纯数字版本,例如 2.3.0。如果发布流程还需要 rc1、提交哈希或构建时间,不要把所有信息都硬塞进 project() 的数字版本中,可以额外定义发布标签或提交标识,再通过同一份模板生成。
用于用户支持和故障定位时,最重要的是保证程序自报版本与发布物一致。只要版本来源保持单一,并把 --version 纳入发布验收,就能显著减少“到底运行了哪个构建”的确认成本。