深入浅出 CMake 项目实战：实现语义化版本控制与自动化集成

在C++项目开发中，无论是独立的应用程序还是供他人使用的库，一个清晰、可追溯的版本号都至关重要。它不仅是项目的“身份证”，更是管理依赖、协同开发以及实现持续集成与交付（CI/CD）的基石。本文将介绍如何在CMake构建系统中，以多种灵活的方式管理和集成版本信息，让版本控制变得自动化且可靠。如果你对C++工程化实践有更多兴趣，欢迎来云栈社区交流探讨。

一、版本号管理

在实际的项目开发中，不同的软件、库以及独立的开发模块等，都需要一个显式的版本匹配机制。这种机制不仅能防止依赖各方因协同不一致而引发工程问题，还能在出现故障时，帮助我们快速定位问题的大致范围。通常情况下，我们会使用一个格式化的“版本号”来唯一标识某个特定的软件状态。

在正规的软件项目中，我们常常会看到软件后面附有长长的版本ID。这些ID的定义方式主要有以下几种：

1. 自定义
   这种方式非常灵活，但可能不被外界广泛认可，或者在对接某些特定平台或规范时存在兼容性问题。

2. 行（企）业定义
   本质上，这与自定义区别不大。但在大中型企业或特定行业领域（如汽车、金融），可能存在内部或行业公认的严格标准，其规范性和通用性比完全的自定义前进了一大步。

3. 国家或国际标准
   这种版本管理机制最为标准化，例如在某些高度规范的行业（如医药、航空航天）都有国家级乃至国际通用的版本管理标准。这种标准更适合大型组织或对安全性、可追溯性要求极高的场景。

当然，版本号的具体形式也非常灵活。它既可以用简单的自然语言描述，也可以采用类似时间戳、构建编号等标签进行说明。这些细节定义通常由项目管理者或架构师来制定。你甚至可以将多种信息组合成一个版本描述集合，具体如何设计，就见仁见智了。

二、软件版本的发布形式

软件的版本迭代和发布节奏，往往会根据项目类型、团队工作流和业务需求的不同而有所差异。一般来说，软件的发布主要分为以下几种模式：

1. 持续交付
   这种模式适合于采用敏捷开发或DevOps实践的互联网应用，其特点是需要快速、频繁地进行小版本迭代和发布。

2. 固定周期发布
   这在许多传统软件或开源项目中比较常见。团队每积累一段时间（如每季度、每半年）的功能和修复后，进行一次集中的、较为完善的版本升级和发布。

3. 按需发布
   这种情况常见于对线上问题响应要求高的场景，特别是针对紧急漏洞修复和重要补丁的发布，不受固定周期限制。

随着软件依赖日益复杂和项目规模不断扩大，现代软件开发中的版本管理大多已借助专门的工具链（如Git, CI/CD平台）来自动化处理，版本号的递增和记录也由工具代为完成。但在不少情况下，我们仍然需要一种灵活的方式，在构建阶段手动或半自动地注入和控制版本信息。

三、利用CMake进行版本号控制

在C++开发中，如果使用CMake作为构建系统，那么我们可以很方便地借助CMake本身来管理项目版本号。这样一来，版本信息就能自动集成到构建产物中，并顺利传递到后续的CI/CD流水线中。下面介绍几种基础的实现方式，通过它们你可以快速掌握相关应用方法。

1. 在CMakeLists.txt中直接指定

这是最直接的方法。你可以在项目的 CMakeLists.txt 文件中直接设置版本变量。

set(PROJECT_VERSION_MAJOR 0)
set(PROJECT_VERSION_MINOR 0)
set(PROJECT_VERSION_PATCH 10)
set(PROJECT_VERSION "${PROJECT_VERSION_MAJOR}.${PROJECT_VERSION_MINOR}.${PROJECT_VERSION_PATCH}")

或者，使用 project 命令的 VERSION 参数来一步到位：

project(${exeTarget} LANGUAGES CXX VERSION 0.0.10)

2. 从外部文件读取版本号

为了将版本信息与构建脚本解耦，你可以将版本号单独写在一个文件中（例如 version.txt），然后在CMake中读取并解析它。

首先，创建一个 version.txt 文件，内容如下：

0.1.10

然后，在 CMakeLists.txt 中编写读取逻辑：

# 读取版本信息文件
file(READ "${CMAKE_CURRENT_SOURCE_DIR}/VERSION.txt" VERSION_STRING)
string(STRIP "${VERSION_STRING}" VERSION_STRING)

# 解析版本号的主版本、次版本和修订号
string(REPLACE "." ";" VERSION_LIST "${VERSION_STRING}")
list(GET VERSION_LIST 0 PROJECT_VERSION_MAJOR)
list(GET VERSION_LIST 1 PROJECT_VERSION_MINOR)
list(GET VERSION_LIST 2 PROJECT_VERSION_PATCH)

# 设置项目版本
project(MyProject VERSION ${VERSION_STRING})

3. 通过配置文件自动生成版本头文件

这是一种更强大、更自动化的方法。它可以生成一个包含丰富版本信息的C++头文件，供源代码直接使用，并且可以集成Git提交哈希、构建时间等信息。

首先，我们创建一个模板文件 version.hpp.in：

#pragma once
#include <string_view>

namespace MY_PROJECT::VERSION {
constexpr int major { @PROJECT_VERSION_MAJOR@ };
constexpr int minor { @PROJECT_VERSION_MINOR@ };
constexpr int patch { @PROJECT_VERSION_PATCH@ };
constexpr std::string_view gitcommit{ "@GIT_HASH@" } ;
constexpr std::string_view full{ "v@PROJECT_VERSION@-@BUILD_TIME@-@GIT_HASH@" };
}

注意：@PROJECT_VERSION_MAJOR@、@GIT_HASH@ 这类用 @ 包围的变量是CMake需要替换的占位符。

然后，在 CMakeLists.txt 中，我们需要获取Git信息，并利用 configure_file 命令将模板文件“转化”为正式的头文件：

# 获取当前Git提交的短哈希（如果项目在Git仓库中）
find_package(Git)
if(GIT_FOUND)
    execute_process(
        COMMAND ${GIT_EXECUTABLE} rev-parse --short HEAD
        WORKING_DIRECTORY ${CMAKE_CURRENT_SOURCE_DIR}
        OUTPUT_VARIABLE GIT_HASH
        OUTPUT_STRIP_TRAILING_WHITESPACE
        ERROR_QUIET
    )
endif()
if(NOT GIT_HASH)
    set(GIT_HASH "unknown")
endif()

# 生成构建时间戳
string(TIMESTAMP BUILD_TIME "%y%m%d_%H%M%S" UTC)

# 将模板文件 version.hpp.in 配置为最终的 version.hpp
# SELF_DIR 等为项目中的配置路径宏，也可以直接写固定路径，但灵活性会降低
configure_file(${CMAKE_CURRENT_SOURCE_DIR}/version.hpp.in
               ${CMAKE_CURRENT_BINARY_DIR}/version.hpp @ONLY)

# 将生成的头文件目录加入包含路径
target_include_directories(${PROJECT_NAME} PRIVATE ${CMAKE_CURRENT_BINARY_DIR})

经过CMake配置和构建后，${CMAKE_CURRENT_BINARY_DIR} 目录下会生成一个 version.hpp 文件，其内容大致如下：

#pragma once
#include <string_view>

namespace MY_PROJECT::VERSION {
constexpr int major { 0 };
constexpr int minor { 0 };
constexpr int patch { 10 };
constexpr std::string_view gitcommit{ "b945c26" } ;
constexpr std::string_view full{ "v0.0.10-251112_145252-b945c26" };
}

这样，在你的C++源代码中，只需 #include “version.hpp”，就可以直接使用 MY_PROJECT::VERSION::full 等常量来获取丰富的版本信息了，非常方便。

四、总结

当然，CMake的功能远不止于此。你可以针对不同的构建目标（如静态库、动态库）设置特定的版本属性（如 SOVERSION）。不同的平台（如Windows的DLL，Linux的so）对版本文件的命名和处理习惯也有所不同，CMake都提供了相应的支持。此外，你还可以编写更复杂的脚本，实现版本号的自动递增（如与Git tag联动）等高级功能。

本文旨在抛砖引玉，通过一个最小化的可实践原型，为你展示了在CMake项目中集成版本控制的几种清晰路径。选择适合你项目复杂度和团队工作流的方式，就能让版本管理变得井然有序。