configure_file

将文件复制到另一个位置并修改其内容。

configure_file(<input> <output>
               [NO_SOURCE_PERMISSIONS | USE_SOURCE_PERMISSIONS |
                FILE_PERMISSIONS <permissions>...]
               [COPYONLY] [ESCAPE_QUOTES] [@ONLY]
               [NEWLINE_STYLE [UNIX|DOS|WIN32|LF|CRLF]])

在执行输入文件内容的转换的同时，将<input>文件复制到<output>文件。

如果输入文件被修改，构建系统将重新运行 CMake 以重新配置该文件并再次生成构建系统。只有当生成文件的内容发生更改时，它才会被修改并且时间戳会在后续的 cmake 运行中更新。

选项

选项包括

<input>

输入文件的路径。相对路径相对于CMAKE_CURRENT_SOURCE_DIR 的值进行处理。输入路径必须是文件，而不是目录。

<output>

输出文件或目录的路径。相对路径相对于CMAKE_CURRENT_BINARY_DIR 的值进行处理。如果路径命名了一个现有目录，则输出文件将被放置在该目录中，并使用与输入文件相同的文件名。如果路径包含不存在的目录，它们将被创建。

NO_SOURCE_PERMISSIONS

3.19 版本新增。

不要将输入文件的权限传输给输出文件。复制的文件权限默认为标准的 644 值（-rw-r--r--）。

USE_SOURCE_PERMISSIONS

在 3.20 版本中添加。

将输入文件的权限传输给输出文件。这是默认行为，如果未给出三个与权限相关的关键字（NO_SOURCE_PERMISSIONS、USE_SOURCE_PERMISSIONS 或 FILE_PERMISSIONS）中的任何一个。 USE_SOURCE_PERMISSIONS 关键字主要用于使调用站点的预期行为更清晰。

FILE_PERMISSIONS <permissions>...

在 3.20 版本中添加。

忽略输入文件的权限，而是为输出文件使用指定的<permissions>。

COPYONLY

复制文件而不替换任何变量引用或其他内容。此选项不能与 NEWLINE_STYLE 一起使用。

ESCAPE_QUOTES

使用反斜杠（C 风格）转义任何替换的引号。

@ONLY

将变量替换限制为 @VAR@ 形式的引用。这对于配置使用 ${VAR} 语法的脚本很有用。

NEWLINE_STYLE <style>

指定输出文件的换行符样式。指定 UNIX 或 LF 用于 \n 换行符，或指定 DOS、WIN32 或 CRLF 用于 \r\n 换行符。此选项不能与 COPYONLY 一起使用。

转换

在输入文件内容中引用的 变量，形式为 @VAR@、${VAR}、$CACHE{VAR}，以及作为 环境变量 引用的 $ENV{VAR}，都将被替换为变量的当前值，如果变量未定义则替换为空字符串。此外，输入行形式为

#cmakedefine VAR ...

将被替换为

#define VAR ...

或

/* #undef VAR */

取决于 VAR 是否在 CMake 中被设置为任何不被 if() 命令视为 false 常量的任何值。行中变量名后面的“...”内容（如果有）将按上述方式处理。

与 #cmakedefine VAR ... 形式的行不同，在 #cmakedefine01 VAR 形式的行中，VAR 本身将扩展为 VAR 0 或 VAR 1，而不是被赋值为 ... 的值。因此，输入行形式为

#cmakedefine01 VAR

将被替换为

#define VAR 0

或

#define VAR 1

输入行形式为 #cmakedefine01 VAR ... 将扩展为 #cmakedefine01 VAR ... 0 或 #cmakedefine01 VAR ... 1，这可能导致未定义的行为。

3.10 版中新增: 结果行（除了 #undef 注释）可以使用 # 字符和 cmakedefine 或 cmakedefine01 词之间的空格和/或制表符进行缩进。这种空格缩进将在输出行中保留。

#  cmakedefine VAR
#  cmakedefine01 VAR

如果 VAR 被定义，将被替换为

#  define VAR
#  define VAR 1

示例

考虑一个包含 foo.h.in 文件的源树

#cmakedefine FOO_ENABLE
#cmakedefine FOO_STRING "@FOO_STRING@"

相邻的 CMakeLists.txt 可以使用 configure_file 来配置头文件

option(FOO_ENABLE "Enable Foo" ON)
if(FOO_ENABLE)
  set(FOO_STRING "foo")
endif()
configure_file(foo.h.in foo.h @ONLY)

这会在对应于此源目录的构建目录中创建一个 foo.h 文件。如果 FOO_ENABLE 选项为开启，则配置的文件将包含

#define FOO_ENABLE
#define FOO_STRING "foo"

否则它将包含

/* #undef FOO_ENABLE */
/* #undef FOO_STRING */

然后可以使用 target_include_directories() 命令将输出目录指定为包含目录

target_include_directories(<target> [SYSTEM] <INTERFACE|PUBLIC|PRIVATE> "${CMAKE_CURRENT_BINARY_DIR}")

以便源文件可以包含头文件，如 #include <foo.h>。

另请参阅

• file(GENERATE)