使用 CMake 进行文件配置

预备知识

configure_file 命令

configure_file 命令是 CMake 中用于处理配置文件的命令。它可以将模板文件中的占位符替换为实际的值，并生成一个新的配置文件。这个命令通常用于生成头文件或其他配置文件，以便在构建过程中使用。

语法

configure_file(<input> <output> [COPYONLY] [ESCAPE_QUOTES] [@ONLY])

• <input>：输入模板文件的路径。
• <output>：输出配置文件的路径。
• COPYONLY：仅复制文件，不进行任何替换。
• ESCAPE_QUOTES：在替换过程中转义双引号。
• @ONLY：仅替换 @VAR@ 形式的占位符，而不替换 ${VAR} 形式的占位符。

CMake 符号 $ 和 @

在 CMake 中，$ 和 @ 都用于变量替换，但它们的使用场景和方式有所不同。

$ 符号

$ 符号用于引用 CMake 变量。CMake 变量的引用形式为 ${VAR_NAME}，其中 VAR_NAME 是变量的名称。

示例

set(PROJECT_NAME "MyProject")
message("Project Name: ${PROJECT_NAME}")

在这个示例中，set 命令定义了一个名为 PROJECT_NAME 的变量，其值为 "MyProject"。message 命令会输出 Project Name: MyProject。

@ 符号

@ 符号通常用于 configure_file 命令中的模板文件，占位符的形式为 @VAR_NAME@。在使用 configure_file 命令生成配置文件时，CMake 会将模板文件中的 @VAR_NAME@ 替换为相应的变量值。

#cmakedefine 命令

#cmakedefine 是 CMake 中用于在配置文件模板中定义条件编译宏的指令。它通常与 configure_file 命令一起使用，以根据 CMake 配置选项生成最终的配置头文件。

基本用法

#cmakedefine 的基本语法如下：

#cmakedefine VAR
#cmakedefine VAR VALUE

• VAR 是要定义的变量名。
• VALUE 是可选的值，如果未提供，默认值为 1。
• 只有当 CMakeLists.txt 中的同名变量为真时才会在生成的头文件中定义，区别于#define无论何时都会定义。

基本步骤

使用 CMake 进行文件配置通常涉及以下几个步骤：定义模板文件、配置选项、生成配置文件，并在代码中使用生成的配置文件。

1. 定义模板文件：创建一个模板文件，其中包含需要配置的占位符和条件编译指令。
2. 配置选项：在 CMakeLists.txt 文件中使用 option 命令定义布尔选项。
3. 生成配置文件：使用 configure_file 命令生成最终的配置文件，CMake 会根据配置选项替换模板文件中的占位符和条件编译指令。
4. 在代码中使用生成的配置文件：在需要使用配置的源文件中包含生成的配置文件。

示例

以下是一个完整的示例，展示了如何使用 CMake 进行文件配置。

目录结构

ConfigProject/
├── CMakeLists.txt
├── cmake_config.h.in
└── main.cpp

cmake_config.h.in

// 定义项目名称
#define PROJECT_NAME "${PROJECT_NAME}"

// 定义项目版本
#define PROJECT_VERSION "${PROJECT_VERSION}"

// 定义是否启用特定功能
#cmakedefine ENABLE_FEATURE ${ENABLE_FEATURE}

CMakeLists.txt

cmake_minimum_required(VERSION 3.15)

# 项目名称和版本
project(ConfigProject VERSION 1.0)

# 设置C++标准
set(CMAKE_CXX_STANDARD 11)
set(CMAKE_CXX_STANDARD_REQUIRED True)

# 配置选项
option(ENABLE_FEATURE "Enable feature" OFF)

# 生成配置文件
configure_file(cmake_config.h.in ${CMAKE_BINARY_DIR}/cmake_config.h)

# 包含生成的配置文件目录
include_directories(${CMAKE_BINARY_DIR})

# 添加可执行文件
add_executable(config_project main.cpp)

main.cpp

#include <iostream>

#include "cmake_config.h"

int main(){
  std::cout << "Project Name: " << PROJECT_NAME << std::endl;
  std::cout << "Project Version: " << PROJECT_VERSION << std::endl;

#ifdef ENABLE_FEATURE
  std::cout << "Feature Enabled" << std::endl;
#else
  std::cout << "Feature Disabled" << std::endl;
#endif

  return 0;
}

启用选项的结果

假设我们在配置项目时启用了 ENABLE_FEATURE 选项：

cmake -DENABLE_FEATURE=ON ..

在这种情况下，生成的 config.h 文件将如下所示：

// 定义项目名称
#define PROJECT_NAME "ConfigProject"

// 定义项目版本
#define PROJECT_VERSION "1.0"

// 定义是否启用特定功能
#define ENABLE_FEATURE ON

未启用选项的结果

假设我们在配置项目时未启用 ENABLE_FEATURE 选项：

cmake -DENABLE_FEATURE=OFF ..

在这种情况下，生成的 config.h 文件将如下所示：

// 定义项目名称
#define PROJECT_NAME "ConfigProject"

// 定义项目版本
#define PROJECT_VERSION "1.0"

// 定义是否启用特定功能
/* #undef ENABLE_FEATURE */