CMP0114

3.19 版本新增。

ExternalProject 步骤目标完全采纳其步骤。

cmake ExternalProject_Add() 的 STEP_TARGETS 选项，以及 ExternalProject_Add_StepTargets() 函数，可用于为外部项目的单个步骤创建构建目标。

在 CMake 3.18 及更低版本中，步骤目标存在一些限制

• 步骤目标始终依赖于 ExternalProject_Add() DEPENDS 选项命名的目标，即使并非所有步骤都需要它们。为了允许在没有这些依赖项的情况下创建步骤目标，可以使用 ExternalProject_Add() INDEPENDENT_STEP_TARGETS 选项或 ExternalProject_Add_StepTargets() NO_DEPENDS 选项。然而，添加此类“独立的”步骤目标仅对特定步骤有意义，例如 download、update 和 patch，因为它们不需要任何外部项目的构建依赖项。此外，为依赖于非独立步骤的步骤创建独立步骤目标没有意义。此类规则并未强制执行，不遵循这些规则的项目可能会生成具有混淆和生成器特定行为的构建系统。

• 步骤目标持有实现其步骤的自定义命令的副本，这些副本独立于由 ExternalProject_Add() 创建的主目标中的副本，并且主目标不依赖于步骤目标。在并行构建中，如果同时驱动主目标和步骤目标，则步骤命令的多个副本可能会并发运行并相互竞争。

  此外，在策略 CMP0113 之前，由 Makefile Generators 生成的步骤目标也包含它们所依赖的所有自定义命令。这可能导致即使在串行构建中也会重复执行这些步骤。

在 CMake 3.19 及更高版本中，ExternalProject 模块倾向于采用经过改进的设计来解决这些问题

• 每个步骤都被分类为“独立的”，如果它不依赖于由 ExternalProject_Add() DEPENDS 命名的其他目标。预定义的步骤默认自动分类

  • 以下步骤是独立的：download、update 和 patch。

  • 以下步骤不是独立的：configure、build、test 和 install。

  对于自定义步骤，ExternalProject_Add_Step() 命令提供了一个 INDEPENDENT 选项来将其标记为独立。如果一个步骤依赖于其他非独立步骤，将其标记为独立是错误的。请注意，此处“独立”一词的使用仅指独立于外部目标，并且与步骤对其他步骤的依赖性是正交的。

• 由 ExternalProject_Add() STEP_TARGETS 选项或 ExternalProject_Add_Step() 函数创建的步骤目标，当且仅当其步骤被标记为独立时，它们才是独立的。不再允许使用 ExternalProject_Add() INDEPENDENT_STEP_TARGETS 选项和 ExternalProject_Add_StepTargets() NO_DEPENDS 选项。

• 步骤目标在创建时，完全负责持有实现其步骤的自定义命令。由 ExternalProject_Add() 创建的主目标依赖于步骤目标，并且步骤目标相互依赖。目标级别的依赖关系匹配每个步骤自定义命令所使用的文件级别的依赖关系。

  当使用 ExternalProject_Add() 的 UPDATE_DISCONNECTED 或 TEST_EXCLUDE_FROM_MAIN 选项，或为自定义步骤使用 ExternalProject_Add_Step() 的 EXCLUDE_FROM_MAIN 选项时，可能会自动创建某些步骤目标。这些步骤目标是为了容纳主目标和已断开连接的步骤目标通常依赖的步骤。

策略 CMP0114 为尚未更新以期望新行为的项目提供了兼容性。OLD 此策略的行为是使用 3.18 及更低版本的上述文档行为。NEW 此策略的行为是使用 3.19 及更高版本倾向于采用的上述文档行为。

此策略是在 CMake 版本 3.19 中引入的。它可以通过 cmake_policy() 或 cmake_minimum_required() 设置。如果未设置，CMake 会发出警告并使用 OLD 行为。

注意

策略的 OLD 行为 按照定义已被弃用，并可能在未来的 CMake 版本中被移除。