add_custom_target

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

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]
                  [JOB_SERVER_AWARE <bool>]
                  [VERBATIM] [USES_TERMINAL]
                  [COMMAND_EXPAND_LISTS]
                  [SOURCES src1 [src2...]])

使用给定的名称添加一个执行给定命令的目标。该目标没有输出文件，并且始终被视为过时，即使命令尝试创建一个与目标同名的文件。请使用 add_custom_command() 命令来生成具有依赖项的文件。默认情况下，没有任何内容依赖于自定义目标。请使用 add_dependencies() 命令来添加或删除与其他目标的依赖项。

选项包括

ALL

指示此目标应添加到默认构建目标中，以便每次都能运行它（命令不能调用 ALL）。

BYPRODUCTS

版本 3.2 中新增。

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

请参阅策略 CMP0058 了解此功能的动机。

副产品的显式指定由 Ninja 生成器支持，用于告知 ninja 构建工具在缺少副产品时如何重新生成它们。当其他构建规则（例如自定义命令）依赖于副产品时，它也很有用。Ninja 要求任何生成的依赖于其他规则的文件都有一个构建规则，即使有仅顺序依赖项，以确保副产品在依赖项构建之前可用。

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

在版本 3.20 中添加: BYPRODUCTS 的参数可以使用受限的 生成器表达式。不允许使用 与目标相关的表达式。

在版本 3.28 中更改: 在使用了 文件集 的自定义目标中，副产品现在被视为私有，除非它们被列在一个非私有文件集中。请参阅策略 CMP0154。

COMMAND

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

如果 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

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

COMMENT

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

在版本 3.26 中添加: COMMENT 的参数可以使用 生成器表达式。

DEPENDS

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

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

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

COMMAND_EXPAND_LISTS

版本 3.8 新增。

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

JOB_POOL

版本 3.15 新增。

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

JOB_SERVER_AWARE

版本 3.28 新增。

指定该命令支持 GNU Make 作业服务器。

对于 Unix Makefiles、MSYS Makefiles 和 MinGW Makefiles 生成器，这将为配方行添加 + 前缀。有关更多信息，请参阅 GNU Make 文档。

此选项会被其他生成器静默忽略。

SOURCES

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

VERBATIM

命令的所有参数都将为构建工具进行正确转义，以便调用的命令接收每个参数不变。请注意，在 add_custom_target 看到参数之前，CMake 语言处理器仍然会使用一个级别的转义。建议使用 VERBATIM，因为它能启用正确的行为。当不提供 VERBATIM 时，行为是平台特定的，因为没有对工具特定的特殊字符进行保护。

USES_TERMINAL

版本 3.2 中新增。

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

WORKING_DIRECTORY

使用给定的当前工作目录执行命令。如果它是相对路径，则将其解释为相对于当前源目录的构建树目录。如果未指定，则设置为 CMAKE_CURRENT_BINARY_DIR。

在版本 3.13 中添加: WORKING_DIRECTORY 的参数可以使用 生成器表达式。

Ninja 多配置

在版本 3.20 中添加: add_custom_target 支持 Ninja Multi-Config 生成器的跨配置功能。有关更多信息，请参阅生成器文档。

另请参阅