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
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@ 形式的占位符,能避免模板中的其他 ${...} 文本被意外展开。

c
#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,其他参数则返回用法错误。

c
#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 的单配置生成器中,可以直接完成配置、编译和验证。

bash
cmake -S . -B build -DCMAKE_BUILD_TYPE=Release
cmake --build build
./build/versioned_app --version

CMake 的配置与编译日志会随生成器和编译器不同而变化;关键验证结果是最后一条命令输出的版本号。

预期输出

text
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 纳入发布验收,就能显著减少“到底运行了哪个构建”的确认成本。

按自己的节奏,确认真正理解。

目录与阅读设置

阅读设置

17

记录一个想法

为程序加入版本信息

0 / 10000 · 笔记保存到账号。未提交的修改会在关闭、离开或刷新后丢失。

登录哪都通