添加自定义目标

添加一个没有输出的目标，以便始终构建它。

add_custom_target(Name [ALL] [command1 [args1...]]
                  [COMMAND command2 [args2...] ...]
                  [DEPENDS depend depend depend ... ]
                  [BYPRODUCTS [files...]]
                  [WORKING_DIRECTORY dir]
                  [COMMENT comment]
                  [JOB_POOL job_pool]
                  [VERBATIM] [USES_TERMINAL]
                  [COMMAND_EXPAND_LISTS]
                  [SOURCES src1 [src2...]])

添加具有执行给定命令的给定名称的目标。目标没有输出文件，并且*总是被认为是过时的*，即使命令试图创建一个具有目标名称的文件。使用 add_custom_command() 命令生成具有依赖项的文件。默认情况下，没有什么依赖于自定义目标。使用 add_dependencies() 命令向其他目标添加依赖项或从其他目标添加依赖项。

选项是：

全部

指明这个目标应该被添加到默认的构建目标中，以便它每次都会运行（该命令不能称为 ALL）。

副产品

在 3.2 版本加入.

指定命令预期生成的文件，但其修改时间可能会或可能不会在后续构建中更新。如果副产品名称是相对路径，它将相对于与当前源目录相对应的构建树目录进行解释。每个副产品文件将自动标有 GENERATED 源文件属性。

查看政策 CMP0058 了解此功能背后的动机。

Ninja 生成器支持副产品的显式规范，以告诉 ninja 构建工具如何在副产品丢失时重新生成它们。当其他构建规则（例如自定义命令）依赖于副产品时，它也很有用。 Ninja 需要为任何生成的文件建立规则，而另一个规则所依赖的文件即使存在仅顺序依赖项，以确保副产品在其依赖项构建之前可用。

Makefile 生成器 将在 make clean 期间删除 BYPRODUCTS 和其他 GENERATED 文件。

在 3.20 版本加入: BYPRODUCTS 的参数可以使用一组受限的 generator expressions。 Target-dependent expressions 是不允许的。

命令

指定要在构建时执行的命令行。如果指定了多个 COMMAND，它们将按顺序执行，但 不一定 必须组合成有状态的 shell 或批处理脚本。 （要运行完整脚本，请使用 configure_file() 命令或 file(GENERATE) 命令创建它，然后指定一个 COMMAND 来启动它。）

如果 COMMAND 指定了可执行目标名称（由 add_executable() 命令创建），如果满足以下任一条件，它将自动替换为构建时创建的可执行文件的位置：

  • 目标未被交叉编译（即 CMAKE_CROSSCOMPILING 变量未设置为 true）。

  • 在 3.6 版本加入: 正在交叉编译目标并提供模拟器（即设置其 CROSSCOMPILING_EMULATOR 目标属性）。在这种情况下，CROSSCOMPILING_EMULATOR 的内容将添加到目标可执行文件位置之前的命令中。

如果以上条件都不满足，则假定命令名称是在构建时在 PATH 上找到的程序。

COMMAND 的参数可以使用 generator expressions。使用 TARGET_FILE 生成器表达式稍后在命令行中引用目标的位置（即作为命令参数而不是作为要执行的命令）。

每当以下基于目标的生成器表达式之一用作要执行的命令或在命令参数中提及时，将自动添加目标级依赖项，以便在该自定义目标之前构建提及的目标（请参阅策略 :policy :CMP0112)。

  • TARGET_FILE

  • TARGET_LINKER_FILE

  • TARGET_SONAME_FILE

  • TARGET_PDB_FILE

命令和参数是可选的，如果未指定，将创建一个空目标。

评论

在构建时执行命令之前显示给定的消息。

在 3.26 版本加入: COMMENT 的参数可以使用 generator expressions。

取决于

在同一目录（CMakeLists.txt 文件）中使用 add_custom_command 命令调用创建的自定义命令的参考文件和输出。当构建目标时，它们将被更新。

在 3.16 版本发生变更: 如果任何依赖项是目标或其在同一目录中的任何构建事件的副产品，则会添加目标级依赖项，以确保在构建此目标之前副产品可用。

使用 add_dependencies() 命令添加对其他目标的依赖。

COMMAND_EXPAND_LISTS

在 3.8 版本加入.

COMMAND 参数中的列表将被扩展，包括使用 generator expressions 创建的列表，允许 COMMAND 参数，例如 ${CC} ” -I$<JOIN:$<TARGET_PROPERTY:foo,INCLUDE_DIRECTORIES>,;-I>" foo.cc 被正确扩展。

作业池

在 3.15 版本加入.

为 Ninja 生成器指定一个 pool。与 USES_TERMINAL 不兼容，这意味着 console 池。使用 JOB_POOLS 未定义的池会导致 ninja 在构建时出错。

来源

指定要包含在自定义目标中的其他源文件。指定的源文件将被添加到 IDE 项目文件中，以方便编辑，即使它们没有构建规则。

逐字

命令的所有参数都将为构建工具正确转义，以便调用的命令接收每个参数不变。请注意，在 add_custom_target 甚至看到参数之前，CMake 语言处理器仍然使用一级转义。建议使用“VERBATIM”，因为它可以实现正确的行为。当未给出 VERBATIM 时，行为是特定于平台的，因为没有对特定于工具的特殊字符的保护。

USES_TERMINAL

在 3.2 版本加入.

如果可能，该命令将被授予直接访问终端的权限。使用 Ninja 生成器，这会将命令放在 console pool 中。

工作目录

使用给定的当前工作目录执行命令。如果它是相对路径，它将被解释为相对于当前源目录对应的构建树目录。

在 3.13 版本加入: WORKING_DIRECTORY 的参数可以使用 generator expressions。

忍者多配置

在 3.20 版本加入: add_custom_target 支持 Ninja Multi-Config 生成器的交叉配置功能。有关详细信息，请参阅生成器文档。

也可以看看