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...) 时设置。

3.20 版本新增: BYPRODUCTS 的参数可以使用一组受限的 生成器表达式。依赖于目标的表达式不允许使用。

3.28 版本变更: 在使用文件集的目标中，自定义命令副产品现在被认为是私有的，除非它们在非私有文件集中列出。请参阅策略 CMP0154。

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 参数中的列表将被展开，包括使用 生成器表达式 创建的列表，从而允许诸如 ${CC} "-I$<JOIN:$<TARGET_PROPERTY:foo,INCLUDE_DIRECTORIES>,;-I>" foo.cc 之类的 COMMAND 参数被正确展开。

此关键字不能与 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.20 版本新增: OUTPUT 的参数可以使用一组受限的 生成器表达式。依赖于目标的表达式不允许使用。

3.28 版本变更: 在使用文件集的目标中，自定义命令输出现在被认为是私有的，除非它们在非私有文件集中列出。请参阅策略 CMP0154。

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 生成器（VS 2012 及以上版本）和 Xcode 生成器的支持。同时还增加了对 generator expressions 的支持。

版本 3.29 新增: Ninja 生成器现在会将依赖项合并到其 “deps log” 数据库中，如果该文件未在 OUTPUTS 或 BYPRODUCTS 中列出。

对上述列表之外的生成器使用 DEPFILE 是错误的。

如果 DEPFILE 参数是相对路径，则它应相对于 CMAKE_CURRENT_BINARY_DIR，并且 DEPFILE 内的任何相对路径也应相对于 CMAKE_CURRENT_BINARY_DIR。请参阅策略 CMP0116，对于 Makefile 生成器、Visual Studio 生成器和 Xcode 生成器，该策略始终为 NEW。

此关键字不能与 APPEND 一起使用（请参阅策略 CMP0175）。只能在首次调用 add_custom_command(OUTPUT...) 时为输出文件设置 Depfile。

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 是可能并发构建的独立目标，因此我们通过将其自定义命令放在单独的目标 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 生成器，这些命令行或自定义命令将为特定配置省略，并且不会添加 “empty-string-command”。

这允许为每个配置添加单独的构建事件。

版本 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 生成器的跨配置功能。有关更多信息，请参阅生成器文档。

另请参阅¶

add_custom_target()

add_custom_command¶

生成文件¶

示例：生成文件¶

示例：为多个目标生成文件¶

构建事件¶

示例：构建事件¶

Ninja 多配置¶

另请参阅¶

目录

上一主题

下一主题

本页