add_custom_command¶
向生成的构建系统添加自定义构建规则。
add_custom_command
有两个主要签名。
生成文件¶
第一个签名用于添加自定义命令以生成输出。
add_custom_command(OUTPUT output1 [output2 ...]
COMMAND command1 [ARGS] [args1...]
[COMMAND command2 [ARGS] [args2...] ...]
[MAIN_DEPENDENCY depend]
[DEPENDS [depends...]]
[BYPRODUCTS [files...]]
[IMPLICIT_DEPENDS <lang1> depend1
[<lang2> depend2] ...]
[WORKING_DIRECTORY dir]
[COMMENT comment]
[DEPFILE depfile]
[JOB_POOL job_pool]
[JOB_SERVER_AWARE <bool>]
[VERBATIM] [APPEND] [USES_TERMINAL]
[CODEGEN]
[COMMAND_EXPAND_LISTS]
[DEPENDS_EXPLICIT_ONLY])
这定义了一个命令来生成指定的 OUTPUT
文件。在同一目录(CMakeLists.txt
文件)中创建的目标,如果指定了自定义命令的任何输出作为源文件,则会获得一个规则,以便在构建时使用该命令生成文件。
不要在多个可能并行构建的独立目标中列出输出,否则规则实例可能会冲突。相反,使用 add_custom_target()
命令来驱动该命令,并使其他目标依赖于该命令。请参阅下面的 示例:为多个目标生成文件。
选项包括
APPEND
将
COMMAND
和DEPENDS
选项值附加到指定第一个输出的自定义命令中。此前必须已经调用过此命令,并且使用了相同的输出。如果之前的调用通过生成器表达式指定了输出,则当前调用指定的输出必须在评估生成器表达式后至少在一个配置中匹配。在这种情况下,附加的命令和依赖项适用于所有配置。
当给定
APPEND
时,COMMENT
、MAIN_DEPENDENCY
和WORKING_DIRECTORY
选项当前被忽略,但将来可能会使用。BYPRODUCTS
版本 3.2 中新增。
指定命令预期生成但其修改时间可能不比依赖项新的文件。如果副产品名称是相对路径,它将被解释为相对于当前源目录对应的构建树目录。每个副产品文件都将自动标记为
GENERATED
源文件属性。有关此功能的动机,请参阅策略
CMP0058
。Ninja
生成器支持显式指定副产品,以告知ninja
构建工具在副产品丢失时如何重新生成它们。当其他构建规则(例如自定义命令)依赖于副产品时,它也很有用。Ninja 要求为任何生成的,且被其他规则依赖的文件提供构建规则,即使只有顺序依赖项,也要确保副产品在它们的依赖项构建之前可用。Makefile 生成器 将在
make clean
期间删除BYPRODUCTS
和其他GENERATED
文件。此关键字不能与
APPEND
一起使用(参见策略CMP0175
)。所有副产品必须在第一次调用add_custom_command(OUTPUT...)
时为输出文件设置。COMMAND
指定在构建时执行的命令行。通常会给定至少一个
COMMAND
,但某些模式可能省略它,例如使用APPEND
在单独的调用中添加命令。如果指定了多个
COMMAND
,它们将按顺序执行,但 不 必然组合成有状态的 shell 或批处理脚本。要运行完整的脚本,请使用configure_file()
命令或file(GENERATE)
命令来创建它,然后指定一个COMMAND
来启动它。可选的
ARGS
参数是为了向后兼容,将被忽略。如果
COMMAND
指定了一个可执行目标名称(由add_executable()
命令创建),则在满足以下任一条件时,它将自动替换为构建时创建的可执行文件的位置:目标未进行交叉编译(即
CMAKE_CROSSCOMPILING
变量未设置为 true)。在 3.6 版本加入: 目标正在交叉编译并且提供了模拟器(即其
CROSSCOMPILING_EMULATOR
目标属性已设置)。在这种情况下,CROSSCOMPILING_EMULATOR
的内容将在目标可执行文件位置之前添加到命令中。
如果上述两个条件都不满足,则假定命令名称是在构建时在
PATH
上找到的程序。COMMAND
的参数可以使用生成器表达式
。使用TARGET_FILE
生成器表达式来引用命令行中稍后出现的目标位置(即作为命令参数而不是要执行的命令)。当以下任何基于目标的生成器表达式用作要执行的命令或在命令参数中提及时,将自动添加目标级别依赖项,以确保在任何使用此自定义命令的目标之前构建提及的目标(参见策略
CMP0112
)。TARGET_FILE
TARGET_LINKER_FILE
TARGET_SONAME_FILE
TARGET_PDB_FILE
此目标级别依赖项不添加文件级别依赖项,文件级别依赖项会导致每当可执行文件重新编译时自定义命令重新运行。使用
DEPENDS
选项列出目标名称以添加此类文件级别依赖项。COMMENT
在构建时执行命令之前显示给定的消息。如果给定
APPEND
,此选项将被忽略,但将来版本可能会使用它。在 3.26 版本加入:
COMMENT
的参数可以使用生成器表达式
。DEPENDS
指定命令所依赖的文件。每个参数都按以下方式转换为依赖项:
如果参数是目标名称(由
add_custom_target()
、add_executable()
或add_library()
命令创建),则会创建一个目标级依赖项,以确保在任何使用此自定义命令的目标之前构建该目标。此外,如果目标是可执行文件或库,则会创建一个文件级依赖项,以使自定义命令在目标重新编译时重新运行。如果参数是绝对路径,则在该路径上创建文件级依赖项。
如果参数是已添加到目标或已设置源文件属性的源文件的名称,则在该源文件上创建文件级依赖项。
如果参数是相对路径且存在于当前源目录中,则在该当前源目录中的文件上创建文件级依赖项。
否则,在该当前二进制目录的相对路径上创建文件级依赖项。
如果任何依赖项是同一目录(
CMakeLists.txt
文件)中另一个自定义命令的OUTPUT
,CMake 会自动将其他自定义命令引入到此命令构建的目标中。在 3.16 版本加入: 如果任何依赖项在同一目录中被列为目标或其任何构建事件的
BYPRODUCTS
,则会添加目标级依赖项,以确保副产品可用。如果未指定
DEPENDS
,则只要OUTPUT
丢失,命令就会运行;如果命令实际上没有创建OUTPUT
,则规则将始终运行。在 3.1 版本加入:
DEPENDS
的参数可以使用生成器表达式
。COMMAND_EXPAND_LISTS
版本 3.8 新增。
COMMAND
参数中的列表将被展开,包括那些用生成器表达式
创建的列表,从而使COMMAND
参数(例如${CC} "-I$<JOIN:$<TARGET_PROPERTY:foo,INCLUDE_DIRECTORIES>,;-I>" foo.cc
)能够正确展开。此关键字不能与
APPEND
一起使用(参见策略CMP0175
)。如果附加的命令需要设置此选项,则必须在第一次调用add_custom_command(OUTPUT...)
时为输出文件设置。CODEGEN
在版本 3.31 中添加。
将自定义命令添加到全局
codegen
目标,该目标可用于执行自定义命令,同时避免大部分构建图。此选项仅受 Ninja 生成器 和 Makefile 生成器 支持,其他生成器会忽略此选项。此外,仅当策略
CMP0171
设置为NEW
时才允许此选项。此关键字不能与
APPEND
一起使用(参见策略CMP0175
)。它只能在第一次调用add_custom_command(OUTPUT...)
时为输出文件设置。IMPLICIT_DEPENDS
请求扫描输入文件的隐式依赖项。给定的语言指定应使用的相应依赖项扫描器。目前仅支持
C
和CXX
语言扫描器。IMPLICIT_DEPENDS
列表中的每个文件都必须指定语言。从扫描中发现的依赖项会在构建时添加到自定义命令的依赖项中。请注意,IMPLICIT_DEPENDS
选项目前仅支持 Makefile 生成器,其他生成器将忽略。注意
此选项不能与
DEPFILE
选项同时指定。JOB_POOL
版本 3.15 新增。
为
Ninja
生成器指定一个池
。与USES_TERMINAL
不兼容,后者表示console
池。使用未由JOB_POOLS
定义的池会导致 ninja 在构建时出错。此关键字不能与
APPEND
一起使用(参见策略CMP0175
)。作业池只能在第一次调用add_custom_command(OUTPUT...)
时为输出文件指定。JOB_SERVER_AWARE
版本 3.28 新增。
指定命令是否是 GNU Make 作业服务器感知的。
对于
Unix Makefiles
、MSYS Makefiles
和MinGW Makefiles
生成器,这将向配方行添加+
前缀。有关详细信息,请参阅 GNU Make 文档。其他生成器会悄悄忽略此选项。
此关键字不能与
APPEND
一起使用(参见策略CMP0175
)。作业服务器感知只能在第一次调用add_custom_command(OUTPUT...)
时为输出文件指定。
MAIN_DEPENDENCY
指定命令的主要输入源文件。这与给定给
DEPENDS
选项的任何值一样处理,但也会建议 Visual Studio 生成器 在何处挂载自定义命令。每个源文件最多可以有一个命令将其指定为其主要依赖项。编译命令(例如,用于库或可执行文件)算作隐式主要依赖项,它将被自定义命令规范静默覆盖。如果给定
APPEND
,此选项目前被忽略,但将来版本可能会使用它。OUTPUT
指定命令预期生成的文件。每个输出文件都将自动标记为
GENERATED
源文件属性。如果自定义命令的输出实际上并未作为文件创建在磁盘上,则应使用SYMBOLIC
源文件属性标记。如果输出文件名是相对路径,则其绝对路径将通过以下方式确定:
相对于当前源目录对应的构建目录(
CMAKE_CURRENT_BINARY_DIR
),或当前源目录(
CMAKE_CURRENT_SOURCE_DIR
)。
构建目录中的路径优先,除非源树中的路径在当前目录中其他地方被提及为绝对源文件路径。
输出文件路径不能包含
<
或>
字符。在 3.30 版本变更: 输出文件路径现在可以使用
#
字符,但使用Borland Makefiles
生成器时除外。USES_TERMINAL
版本 3.2 中新增。
如果可能,该命令将直接访问终端。对于
Ninja
生成器,这会将命令放置在console
池
中。此关键字不能与
APPEND
一起使用(参见策略CMP0175
)。如果附加的命令需要访问终端,则必须在第一次调用add_custom_command(OUTPUT...)
时为输出文件设置。VERBATIM
命令的所有参数都将为构建工具正确转义,以便被调用的命令接收每个参数不变。请注意,在
add_custom_command
看到参数之前,CMake 语言处理器仍然会使用一层转义。建议使用VERBATIM
,因为它能确保正确行为。未给定VERBATIM
时,行为是平台特定的,因为没有对工具特定特殊字符的保护。此关键字不能与
APPEND
一起使用(参见策略CMP0175
)。如果附加的命令需要被视为VERBATIM
,则必须在第一次调用add_custom_command(OUTPUT...)
时为输出文件设置。WORKING_DIRECTORY
使用给定的当前工作目录执行命令。如果它是相对路径,它将被解释为相对于当前源目录对应的构建树目录。
如果给定
APPEND
,此选项目前被忽略,但将来版本可能会使用它。在 3.13 版本加入:
WORKING_DIRECTORY
的参数可以使用生成器表达式
。DEPFILE
3.7 版本中新增。
指定一个 depfile,其中包含自定义命令的依赖项。它通常由自定义命令本身发出。此关键字只能在生成器支持时使用,如下所述。
预期的格式,与
gcc
使用选项-M
生成的格式兼容,与生成器或平台无关。正式语法,使用带有常规扩展的 BNF 符号指定,如下:
depfile ::=
rule
* rule ::=targets
(':' (separator
dependencies
?)?)?eol
targets ::=target
(separator
target
)*separator
* target ::=pathname
dependencies ::=dependency
(separator
dependency
)*separator
* dependency ::=pathname
separator ::= (space
|line_continue
)+ line_continue ::= '\'eol
space ::= ' ' | '\t' pathname ::=character
+ character ::=std_character
|dollar
|hash
|whitespace
std_character ::= <any character except '$', '#' or ' '> dollar ::= '$$' hash ::= '\#' whitespace ::= '\ ' eol ::= '\r'? '\n'注意
作为
pathname
的一部分,任何斜杠和反斜杠都被解释为目录分隔符。在 3.7 版本加入:
Ninja
生成器自关键字首次添加以来就支持DEPFILE
。在 3.17 版本加入: 添加了
Ninja Multi-Config
生成器,其中包含对DEPFILE
关键字的支持。在 3.20 版本加入: 增加了对 Makefile 生成器 的支持。
注意
DEPFILE
不能与 Makefile 生成器 的IMPLICIT_DEPENDS
选项同时指定。在 3.21 版本加入: 增加了对 Visual Studio 2012 及更高版本的 Visual Studio 生成器 和
Xcode
生成器的支持。同时增加了对生成器表达式
的支持。在 3.29 版本加入: 如果文件未列在
OUTPUTS
或BYPRODUCTS
中,Ninja 生成器 现在将把依赖项合并到其“deps log”数据库中。将
DEPFILE
与上述未列出的生成器一起使用会导致错误。如果
DEPFILE
参数是相对路径,它应相对于CMAKE_CURRENT_BINARY_DIR
,并且DEPFILE
内部的任何相对路径也应相对于CMAKE_CURRENT_BINARY_DIR
。参见策略CMP0116
,它对于 Makefile 生成器、Visual Studio 生成器 和Xcode
生成器始终为NEW
。此关键字不能与
APPEND
一起使用(参见策略CMP0175
)。依赖文件只能在第一次调用add_custom_command(OUTPUT...)
时为输出文件设置。
DEPENDS_EXPLICIT_ONLY
在 3.27 版本中新增。
表示命令的
DEPENDS
参数代表命令所需的所有文件,不需要隐式依赖项。如果没有此选项,如果任何目标使用自定义命令的输出,CMake 将把该目标的依赖项视为自定义命令的隐式依赖项,以防自定义命令需要这些目标隐式创建的文件。
通过将
CMAKE_ADD_CUSTOM_COMMAND_DEPENDS_EXPLICIT_ONLY
设置为ON
,可以在所有自定义命令上启用此选项。此关键字不能与
APPEND
一起使用(参见策略CMP0175
)。它只能在第一次调用add_custom_command(OUTPUT...)
时为输出文件设置。只有 Ninja 生成器 实际使用此信息来删除不必要的隐式依赖项。
另请参阅
OPTIMIZE_DEPENDENCIES
目标属性,它可能在某些情况下提供另一种减少目标依赖项影响的方法。
示例:生成文件¶
自定义命令可用于生成源文件。例如,以下代码:
add_custom_command(
OUTPUT out.c
COMMAND someTool -i ${CMAKE_CURRENT_SOURCE_DIR}/in.txt
-o out.c
DEPENDS ${CMAKE_CURRENT_SOURCE_DIR}/in.txt
VERBATIM)
add_library(myLib out.c)
添加一个自定义命令来运行 someTool
生成 out.c
,然后将生成的源作为库的一部分进行编译。生成规则将在 in.txt
更改时重新运行。
在 3.20 版本加入: 可以使用生成器表达式来指定每个配置的输出。例如,以下代码:
add_custom_command(
OUTPUT "out-$<CONFIG>.c"
COMMAND someTool -i ${CMAKE_CURRENT_SOURCE_DIR}/in.txt
-o "out-$<CONFIG>.c"
-c "$<CONFIG>"
DEPENDS ${CMAKE_CURRENT_SOURCE_DIR}/in.txt
VERBATIM)
add_library(myLib "out-$<CONFIG>.c")
添加一个自定义命令,运行 someTool
来生成 out-<config>.c
,其中 <config>
是构建配置,然后将生成的源作为库的一部分进行编译。
在 3.31 版本加入: 使用 CODEGEN
选项将自定义命令的输出添加到内置的 codegen
目标。这对于在不构建整个项目的情况下使生成的代码可用于静态分析很有用。例如:
add_executable(someTool someTool.c)
add_custom_command(
OUTPUT out.c
COMMAND someTool -o out.c
CODEGEN)
add_library(myLib out.c)
用户可以构建 codegen
目标来生成 out.c
。someTool
作为依赖项被构建,但 myLib
完全不构建。
示例:为多个目标生成文件¶
如果多个独立目标需要相同的自定义命令输出,则必须将其附加到一个单一的自定义目标上,所有其他目标都依赖于该目标。考虑以下示例:
add_custom_command(
OUTPUT table.csv
COMMAND makeTable -i ${CMAKE_CURRENT_SOURCE_DIR}/input.dat
-o table.csv
DEPENDS ${CMAKE_CURRENT_SOURCE_DIR}/input.dat
VERBATIM)
add_custom_target(generate_table_csv DEPENDS table.csv)
add_custom_command(
OUTPUT foo.cxx
COMMAND genFromTable -i table.csv -case foo -o foo.cxx
DEPENDS table.csv # file-level dependency
generate_table_csv # target-level dependency
VERBATIM)
add_library(foo foo.cxx)
add_custom_command(
OUTPUT bar.cxx
COMMAND genFromTable -i table.csv -case bar -o bar.cxx
DEPENDS table.csv # file-level dependency
generate_table_csv # target-level dependency
VERBATIM)
add_library(bar bar.cxx)
输出 foo.cxx
仅由目标 foo
需要,输出 bar.cxx
仅由目标 bar
需要,但 这两个 目标都间接需要 table.csv
。由于 foo
和 bar
是可能并发构建的独立目标,我们通过将生成 table.csv
的自定义命令放在一个单独的目标 generate_table_csv
中,来防止它们竞相生成 table.csv
。生成 foo.cxx
和 bar.cxx
的自定义命令都指定了对 generate_table_csv
的目标级依赖,因此使用它们的目标 foo
和 bar
将在目标 generate_table_csv
构建完成后才开始构建。
构建事件¶
第二个签名将自定义命令添加到目标,例如库或可执行文件。这对于在构建目标之前或之后执行操作非常有用。该命令成为目标的一部分,并且只在目标本身构建时执行。如果目标已经构建,则命令不会执行。
add_custom_command(TARGET <target>
PRE_BUILD | PRE_LINK | POST_BUILD
COMMAND command1 [ARGS] [args1...]
[COMMAND command2 [ARGS] [args2...] ...]
[BYPRODUCTS [files...]]
[WORKING_DIRECTORY dir]
[COMMENT comment]
[VERBATIM]
[COMMAND_EXPAND_LISTS]
[USES_TERMINAL])
这定义了一个新的命令,它将与构建指定的 <target>
相关联。<target>
必须在当前目录中定义;不能指定在其他目录中定义的目标。
命令何时发生取决于以下哪项被指定:
PRE_BUILD
此选项对于 Visual Studio 生成器 具有独特的行为。当使用 Visual Studio 生成器时,该命令将在目标内执行任何其他规则之前运行。对于所有其他生成器,此选项的行为与
PRE_LINK
相同。因此,建议避免使用PRE_BUILD
,除非已知正在使用 Visual Studio 生成器。PRE_LINK
在源文件编译后,但在链接二进制文件或运行静态库的库管理员或归档工具之前运行。这对于由
add_custom_target()
命令创建的目标未定义。POST_BUILD
在目标内所有其他规则执行完毕后运行。
使用 TARGET
形式时,项目应始终指定上述三个关键字之一。请参见策略 CMP0175
。
签名中显示的所有其他关键字与 add_custom_command(OUTPUT)
形式的命令具有相同的含义。必须至少给定一个 COMMAND
,请参阅策略 CMP0175
。
注意
由于生成器表达式可用于自定义命令,因此可以定义 COMMAND
行或整个自定义命令,它们在某些配置下评估为空字符串。对于 Visual Studio 生成器,这些命令行或自定义命令将在特定配置下省略,并且不会添加“空字符串命令”。
这允许为每个配置添加单独的构建事件。
在 3.21 版本加入: 支持依赖于目标的生成器表达式。
在 3.29 版本加入: <target>
可以是 ALIAS 目标。
示例:构建事件¶
POST_BUILD
事件可用于在链接后处理二进制文件。例如,代码:
add_executable(myExe myExe.c)
add_custom_command(
TARGET myExe POST_BUILD
COMMAND someHasher -i "$<TARGET_FILE:myExe>"
-o "$<TARGET_FILE:myExe>.hash"
VERBATIM)
将在链接后运行 someHasher
以在可执行文件旁边生成一个 .hash
文件。
在 3.20 版本加入: 可以使用生成器表达式来指定每个配置的副产品。例如,以下代码:
add_library(myPlugin MODULE myPlugin.c)
add_custom_command(
TARGET myPlugin POST_BUILD
COMMAND someHasher -i "$<TARGET_FILE:myPlugin>"
--as-code "myPlugin-hash-$<CONFIG>.c"
BYPRODUCTS "myPlugin-hash-$<CONFIG>.c"
VERBATIM)
add_executable(myExe myExe.c "myPlugin-hash-$<CONFIG>.c")
将在链接 myPlugin
后运行 someHasher
,例如生成一个包含代码的 .c
文件,该代码用于检查 myPlugin
的哈希值,myExe
可执行文件可以在加载前使用该文件进行验证。
Ninja 多配置¶
在 3.20 版本加入: add_custom_command
支持 Ninja Multi-Config
生成器的跨配置功能。有关更多信息,请参阅生成器文档。