CMake configure_file使用教程详解

CMake的configure_file()命令是构建过程中的"动态配置生成器"，它能将模板文件（如.in文件）复制到构建目录，并替换其中的变量或根据CMake逻辑生成预处理器宏。相比简单拷贝，它能让生成的文件内容随你的CMake配置动态变化。

下面表格汇总了它的核心语法和选项：

参数/选项	描述与用途
`<input>`	输入的模板文件路径。通常是源目录下的文件（如 `config.h.in`）。
`<output>`	输出文件路径。通常位于构建目录（如 `${CMAKE_CURRENT_BINARY_DIR}/config.h`）。
`@ONLY`	限制只替换 `@VAR@` 形式的变量，不替换 `${VAR}` 形式。适用于配置脚本文件。
`COPYONLY`	只复制文件，不进行任何替换。用于纯文件拷贝。
`ESCAPE_QUOTES`	对替换内容中的引号进行反斜杠转义（C风格）。
`NEWLINE_STYLE`	指定输出文件的换行符，如 `UNIX`(`\n`) 或 `DOS`(`\r\n`)。
`FILE_PERMISSIONS`等	控制输出文件的权限（CMake 3.20+）。

📝 主要应用场景与示例

configure_file() 最常用于生成 配置头文件。

1. 生成包含变量和宏定义的头文件

假设你有一个模板文件 config.h.in：

c 复制代码

// config.h.in
#define PROJECT_NAME "@PROJECT_NAME@"
#define PROJECT_VERSION "@PROJECT_VERSION@"

#cmakedefine FEATURE_A_ENABLED
#cmakedefine01 FEATURE_B_ENABLED

在 CMakeLists.txt 中：

cmake 复制代码

set(PROJECT_NAME "MyAwesomeApp")
set(PROJECT_VERSION "2.1.0")
option(FEATURE_A_ENABLED "Enable Feature A" ON) # 默认为ON
set(FEATURE_B_ENABLED OFF) # 显式设置为OFF

configure_file(config.h.in ${CMAKE_CURRENT_BINARY_DIR}/config.h)

根据上述配置，生成的 config.h 内容如下：

c 复制代码

// config.h
#define PROJECT_NAME "MyAwesomeApp"
#define PROJECT_VERSION "2.1.0"

#define FEATURE_A_ENABLED
#define FEATURE_B_ENABLED 0

说明：

@VAR@ 被直接替换为对应的字符串值。
#cmakedefine VAR：如果变量被设置为真（非假值，如ON、1），则生成 #define VAR；否则生成 /* #undef VAR */。
#cmakedefine01 VAR：直接生成 #define VAR 1（真）或 #define VAR 0（假）。

生成后，你需要用 target_include_directories() 将输出目录（如 ${CMAKE_CURRENT_BINARY_DIR}）添加到头文件搜索路径中，这样源代码才能 #include <config.h>。

2. 纯文件拷贝

如果你只想复制文件而不替换任何内容，应使用 COPYONLY 选项。

cmake 复制代码

configure_file(original.txt ${CMAKE_CURRENT_BINARY_DIR}/copy.txt COPYONLY)

⚖️ 与 `file(COPY)` 命令的对比

configure_file(COPYONLY) 和 file(COPY) 都可用于复制文件，但有一个关键区别：

特性	`configure_file( ... COPYONLY)`	`file(COPY ...)`
依赖跟踪	自动建立。如果输入模板文件内容更改，CMake会重新运行并更新输出。	无。复制操作在配置阶段执行一次，之后文件变更不会触发重建。
主要用途	需要依赖跟踪的纯文件复制。	一次性的资源文件拷贝，不需要依赖跟踪。

一个实际案例是xz项目，它用 configure_file(COPYONLY) 替代了之前的 add_custom_command，以简化头文件拷贝并自动获得依赖跟踪。

💡 最佳实践与注意事项

路径清晰 ：建议对输出路径使用 CMAKE_CURRENT_BINARY_DIR 等绝对路径变量，明确文件生成位置。
分离生成与源码 ：生成的配置文件应放在构建目录，不要污染源代码树。
内容变更检测 ：configure_file() 很智能，只有当生成的文件内容确实改变时，才会更新其时间戳，避免不必要的重新编译。
模板文件命名 ：习惯上为模板文件添加 .in 后缀（如 config.h.in），以区别于最终生成的文件。
变量替换范围 ：当模板中需要保留 ${} 语法（例如Shell脚本）时，务必使用 @ONLY 选项，限制只替换 @VAR@。

🔧 简单对比：`configure_file` vs `file(WRITE)`

除了拷贝，CMake的 file(WRITE) 也能生成文件，但方式不同：

命令	工作方式	适用场景
`configure_file()`	基于模板替换。内容主体在独立的模板文件中。	内容复杂、需要复用模板、或需要根据条件生成预处理器宏时。
`file(WRITE)`	在CMakeLists中直接拼接内容并写入。	内容非常简短、或完全由CMake逻辑动态生成时。

总的来说，configure_file() 是CMake中实现配置式构建的核心命令。掌握它，你就能轻松地根据不同的构建选项（如Debug/Release、不同的平台或特性开关）生成定制化的源代码文件了。

在 config.h.in 模板文件中，CMake 使用一套特定的语法规则，通过 configure_file() 命令将其智能地转换为 C/C++ 头文件。这主要分为两大类：直接变量替换 和条件宏生成。

📝 config.h.in 核心语法规则

为了让你快速掌握，我将核心语法规则总结为下表：

语法	在 `.in` 文件中的写法	在 CMake 中的状态	在 `.h` 文件中的生成结果	核心用途与说明
变量替换	`@CMAKE_VARIABLE@`	`set(CMAKE_VARIABLE "value")`	`"value"`	直接替换。将 CMake 变量的值作为字符串填入。
条件宏 (1)	`#cmakedefine FEATURE_ENABLED`	`set(FEATURE_ENABLED ON)` 或 `option(... ON)`	`#define FEATURE_ENABLED`	如果 CMake 变量为真，则生成 `#define`。
	`#cmakedefine FEATURE_ENABLED`	`set(FEATURE_ENABLED OFF)` 或未定义/假值	`/* #undef FEATURE_ENABLED */`	如果为假，则生成一条被注释掉的 `#undef`。
条件宏 (2)	`#cmakedefine01 FEATURE_ENABLED`	`set(FEATURE_ENABLED ON)` 或 `option(... ON)`	`#define FEATURE_ENABLED 1`	总是生成定义。为真时定义为 `1`。
	`#cmakedefine01 FEATURE_ENABLED`	`set(FEATURE_ENABLED OFF)` 或未定义/假值	`#define FEATURE_ENABLED 0`	总是生成定义。为假时定义为 `0`。

🔧 转换机制与详细示例

让我们通过一个更丰富的 config.h.in 例子来直观感受整个转换过程。

1. 模板文件 config.h.in

cpp 复制代码

// config.h.in - CMake 配置文件模板
#pragma once

// 1. 直接变量替换
#define APP_NAME "@PROJECT_NAME@"
#define APP_VERSION_MAJOR @PROJECT_VERSION_MAJOR@
#define APP_VERSION_MINOR @PROJECT_VERSION_MINOR@

// 2. 条件编译宏 (传统方式)
#cmakedefine ENABLE_LOGGING
#cmakedefine USE_GPU

// 3. 条件编译宏 (01方式，推荐用于布尔值)
#cmakedefine01 SUPPORT_FEATURE_X

// 4. 带值的变量定义
#cmakedefine CACHE_SIZE @CACHE_SIZE@

2. 在 CMakeLists.txt 中配置变量

cmake 复制代码

# 定义基本项目信息
set(PROJECT_NAME "MyApp")
set(PROJECT_VERSION_MAJOR 2)
set(PROJECT_VERSION_MINOR 10)

# 定义开关选项
option(ENABLE_LOGGING "Enable debug logging" ON) # 默认为 ON (真)
set(USE_GPU OFF) # 显式设置为 OFF (假)
set(SUPPORT_FEATURE_X ON) # 设置为 ON (真)

# 定义带数值的配置
set(CACHE_SIZE 256)

# 执行文件生成
configure_file(config.h.in ${CMAKE_CURRENT_BINARY_DIR}/config.h)

3. 生成的 config.h 文件

运行 CMake 后，你将得到如下内容的头文件：

cpp 复制代码

// config.h - 由 CMake 生成的实际头文件
#pragma once

// 1. 直接变量替换
#define APP_NAME "MyApp"
#define APP_VERSION_MAJOR 2
#define APP_VERSION_MINOR 10

// 2. 条件编译宏 (传统方式)
#define ENABLE_LOGGING
/* #undef USE_GPU */

// 3. 条件编译宏 (01方式，推荐用于布尔值)
#define SUPPORT_FEATURE_X 1

// 4. 带值的变量定义
#define CACHE_SIZE 256

💡 关键要点与最佳实践

#cmakedefine 与 #cmakedefine01 的选择
- 使用 #cmakedefine 当你的代码使用 #ifdef 或 #if defined() 进行检查时。它能在关闭时完全移除定义，可以减小代码体积。
- 使用 #cmakedefine01 当你的代码使用 #if FEATURE_X 进行检查时。它始终存在一个定义（0或1），避免了因未定义宏而可能导致的编译警告，逻辑更一致。这是许多现代项目（如 NeoVim）的推荐做法。
变量作用域 ：确保你在调用 configure_file() 之前，已经设置好了所有需要用到的 CMake 变量。这些变量可以是全局的，也可以是当前目录及子目录中定义的。

在代码中使用：在 C/C++ 源文件中，你可以像使用普通头文件一样包含并使用这些定义：

cpp 复制代码

#include "config.h"

int main() {
    printf("Welcome to %s\n", APP_NAME);

    #ifdef ENABLE_LOGGING
        log_debug("App started");
    #endif

    #if SUPPORT_FEATURE_X
        enable_feature_x(); // 当 SUPPORT_FEATURE_X 为 1 时编译
    #endif

    int buffer[CACHE_SIZE];
    // ...
}

包含路径 ：别忘了在 CMakeLists.txt 中，将生成头文件的目录（通常是 CMAKE_CURRENT_BINARY_DIR）添加到目标的包含路径中：
cmake 复制代码
```
target_include_directories(MyTarget PRIVATE ${CMAKE_CURRENT_BINARY_DIR})
```

🏗️ 实际项目应用

许多大型开源项目都广泛使用此模式：

NeoVim ：在 src/nvim/config.h.in 中，使用大量 #cmakedefine01 来配置平台特性、函数可用性等。
VTK ：在 CMake/vtkTk.h.in 等文件中，使用 @VTK_VERSION@ 等变量定义版本信息。

CMake configure_file使用教程详解

📝 主要应用场景与示例

⚖️ 与 file(COPY) 命令的对比

💡 最佳实践与注意事项

🔧 简单对比：configure_file vs file(WRITE)

📝 config.h.in 核心语法规则

🔧 转换机制与详细示例

💡 关键要点与最佳实践

🏗️ 实际项目应用

⚖️ 与 `file(COPY)` 命令的对比

🔧 简单对比：`configure_file` vs `file(WRITE)`