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 以重新配置该文件，并再次生成构建系统。只有在内容发生更改时，生成的文件才会经过修改并更新其时间戳。
选项¶
选项为
<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 */
具体取决于在 CMake 中是否将 VAR 设置为 if() 命令认为不是假常量的任何值。如果变量名后面有任何 "..." 内容，则按照上述方式进行处理。
与 #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> 包含进来。