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

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

版本 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 pool 中。

WORKING_DIRECTORY

在给定当前工作目录下执行命令。如果是相对路径，则将相对于当前源目录对应的构建树目录进行解释。

版本 3.13 新增： WORKING_DIRECTORY 的参数可以使用 生成器表达式。

Ninja 多配置

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

另请参阅