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>
指定输出文件的新行样式。对于
\n
新行,指定UNIX
或LF
;对于\r\n
新行,指定DOS
、WIN32
或CRLF
。此选项不能与COPYONLY
一起使用。
转换¶
输入文件中以 @VAR@
、${VAR}
、$CACHE{VAR}
形式引用的变量,以及以 $ENV{VAR}
形式引用的环境变量,都将被替换为变量的当前值,如果变量未定义则替换为空字符串。此外,以下形式的输入行
#cmakedefine VAR ...
将被替换为
#define VAR ...
或
/* #undef VAR */
这取决于 VAR
是否在 CMake 中设置为任何不被 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>
。