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 的参数可以使用一组受限的 generator expressions。目标相关的表达式是不允许的。

在版本 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 的参数可以使用 generator expressions。使用 TARGET_FILE 生成器表达式来引用命令行中稍后目标的位置（即，作为命令参数而不是作为要执行的命令）。

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

  • TARGET_FILE

  • TARGET_LINKER_FILE

  • TARGET_SONAME_FILE

  • TARGET_PDB_FILE

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

COMMENT

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

在版本 3.26 中添加：COMMENT 的参数可以使用 generator expressions。

DEPENDS

引用在同一目录（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）被正确展开。

JOB_POOL

在版本 3.15 中添加。

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

JOB_SERVER_AWARE

在版本 3.28 中添加。

指定该命令是 GNU Make job server 感知的。

对于 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 的参数可以使用 generator expressions。

Ninja Multi-Config

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

参见