CMake如何通过变量透明切换多版本子目录并触发自动重编译

核心思路 #

我们通过CMake变量选择目标版本目录+生成编译目录下的跨平台目录映射+配置头文件标记版本变更的组合方案实现需求，全程兼容Windows/Linux系统，同时满足代码无感知、切换自动触发重编译的要求。

具体实现步骤 #

1. 项目目录结构预设 #

先把所有subdir版本放在同级目录，参考结构如下：

项目根目录
├── CMakeLists.txt
├── src/                # 业务代码存储目录
├── subdir_version.h.in # 版本标记头文件模板
└── subdir_versions/    # 存放所有subdir版本的父目录
    ├── subdir1/
    ├── subdir2/
    └── subdir3/

2. 顶层CMakeLists.txt配置 #

第一步：定义切换用的CMake变量

新增可配置的缓存变量，用于指定要使用的subdir版本：

# 定义subdir版本选择变量，默认使用subdir1
set(USE_SUBDIR_VERSION "subdir1" CACHE STRING "选择要使用的subdir版本，可选值：subdir1/subdir2/subdir3")

第二步：校验版本合法性

判断选中的版本目录是否存在，避免配置出错：

set(SUBDIR_SOURCE_DIR "${CMAKE_CURRENT_SOURCE_DIR}/subdir_versions/${USE_SUBDIR_VERSION}")
if(NOT EXISTS "${SUBDIR_SOURCE_DIR}")
    message(FATAL_ERROR "指定的subdir版本 ${USE_SUBDIR_VERSION} 不存在，请检查subdir_versions目录下的版本文件")
endif()

第三步：生成编译目录下的subdir映射目录

用CMake原生的file(CREATE_LINK)创建符号链接，CMake会自动处理Windows/Linux的跨平台逻辑：

# 生成的subdir映射放在编译目录的generated_include子目录下
set(SUBDIR_LINK_DIR "${CMAKE_CURRENT_BINARY_DIR}/generated_include")
set(SUBDIR_TARGET_PATH "${SUBDIR_LINK_DIR}/subdir")

# 每次配置时先删除旧的映射，避免残留旧版本文件
file(REMOVE_RECURSE "${SUBDIR_TARGET_PATH}")
# 创建符号链接指向选中的版本目录
file(CREATE_LINK "${SUBDIR_SOURCE_DIR}" "${SUBDIR_TARGET_PATH}" SYMBOLIC)

注：如果遇到Windows下符号链接权限不足的问题，可以把CREATE_LINK逻辑替换为目录拷贝：file(COPY "${SUBDIR_SOURCE_DIR}" DESTINATION "${SUBDIR_LINK_DIR}/")，再把拷贝后的目录重命名为subdir即可，兼容性更高，仅大目录场景下会有轻微的拷贝耗时。

第四步：添加版本变更标记，触发重编译

创建配置头文件，把当前选中的版本号写入头文件，只要USE_SUBDIR_VERSION变量变更，该头文件就会自动更新，触发全量重编译：

# 生成版本标记头文件
set(SUBDIR_VERSION_HEADER "${SUBDIR_LINK_DIR}/subdir_version.h")
configure_file(
    "${CMAKE_CURRENT_SOURCE_DIR}/subdir_version.h.in"
    "${SUBDIR_VERSION_HEADER}"
    @ONLY
)

在项目根目录新建subdir_version.h.in模板文件，内容如下：

#ifndef SUBDIR_VERSION_H
#define SUBDIR_VERSION_H
#define SUBDIR_VERSION "@USE_SUBDIR_VERSION@"
#endif // SUBDIR_VERSION_H

第五步：给业务目标添加头文件搜索路径

把生成的include目录加到业务目标的头文件搜索路径中，同时添加强制依赖：

# 此处替换为你实际的业务目标名，示例为my_project
add_executable(my_project src/main.cpp)
target_include_directories(my_project
    PUBLIC
        # 加入生成目录后，编译器即可识别<subdir/xxx.h>格式的引入
        "${SUBDIR_LINK_DIR}"
)
# 强制让目标依赖版本头文件，版本变更时自动触发全量重编译
set_target_properties(my_project PROPERTIES
    OBJECT_DEPENDS "${SUBDIR_VERSION_HEADER}"
)

3. 版本切换使用方式 #

编译时通过CMake参数指定版本即可，不需要修改任何业务代码：

# 示例：使用subdir2版本编译
cmake .. -DUSE_SUBDIR_VERSION=subdir2
make

方案优势 #

• 代码完全无感知：业务代码统一写#include "subdir/xxx.h"即可，不需要感知当前使用的版本
• 切换自动触发重编译：只要USE_SUBDIR_VERSION参数变更，configure_file会自动更新版本头文件，CMake会识别依赖变更触发全量重编译，不会出现旧缓存复用的问题
• 跨平台兼容：所有用到的CMake指令都是原生跨平台实现，Windows和Linux下都可正常运行
• 无额外依赖：不需要安装第三方工具，纯CMake原生逻辑实现

内容的提问来源于stack exchange，提问作者Desperado17