CMP0114

在 3.19 版本加入.

ExternalProject 步骤目标完全采用他们的步骤。

ExternalProject_Add() STEP_TARGETS 选项和 ExternalProject_Add_StepTargets() 函数可用于为外部项目的各个步骤创建构建目标。

在 CMake 3.18 及以下版本中，步骤目标有一些限制：

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

  • 步骤目标包含实现其步骤的自定义命令的副本，这些副本与由 ExternalProject_Add() 创建的主要目标中的副本分开，并且主要目标不依赖于步骤目标。在同时驱动主要目标和步骤目标的并行构建中，步骤命令的多个副本可能同时运行并相互竞争。

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

在 CMake 3.19 及更高版本中， ExternalProject 模块更喜欢修改设计来解决这些问题：

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

    • “下载”、“更新”和“补丁”步骤是独立的。

    • “配置”、“构建”、“测试”和“安装”步骤不是。

    对于自定义步骤， 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”为尚未更新以期待新行为的项目提供兼容性。此策略的“旧”行为是使用 3.18 及以下版本中记录的上述行为。此策略的“新”行为是使用 3.19 及更高版本首选的上述记录行为。

此策略是在 CMake 版本 3.19 中引入的。 CMake 版本 |发布|当未设置策略并使用“旧”行为时发出警告。使用 cmake_policy() 命令将其显式设置为 OLD 或 NEW。