cmake_policy¶

管理 CMake 策略设置。有关已定义策略的信息，请参阅 cmake-policies(7) 手册。

随着 CMake 的发展，有时需要更改现有行为以修复错误或改进现有功能的实现。CMake 策略机制旨在帮助保持现有项目在 CMake 新版本引入行为更改时能够构建。每个新的策略（行为更改）都使用 CMP<NNNN> 形式的标识符，其中 <NNNN> 是一个整数索引。与每个策略相关的文档描述了 OLD 和 NEW 行为以及引入该策略的原因。项目可以设置每个策略以选择所需的行为。当 CMake 需要知道使用哪种行为时，它会检查项目指定的设置。如果未提供设置，则假定为 OLD 行为，并会生成一条警告，要求设置该策略。

根据 CMake 版本设置策略¶

cmake_policy 命令用于将策略设置为 OLD 或 NEW 行为。虽然支持单独设置策略，但我们鼓励项目根据 CMake 版本设置策略。

cmake_policy(VERSION <min>[...<max>])¶

版本 3.12 中新增：可选的 <max> 版本。

<min> 和可选的 <max> 都是 major.minor[.patch[.tweak]] 形式的 CMake 版本，并且 ... 是字面量。 <min> 版本必须至少为 2.4，并且最多为 CMake 的运行版本。如果指定了 <max> 版本，则它必须至少为 <min> 版本，但可以超过 CMake 的运行版本。如果 CMake 的运行版本早于 3.12，则额外的 ... 点将被视为版本组件分隔符，导致 ...<max> 部分被忽略，并保留基于 <min> 的 3.12 之前的策略行为。

这指定当前 CMake 代码是为给定范围的 CMake 版本编写的。CMake 运行版本已知并在 <min>（或如果指定了 <max>，则为 <max>）版本或更早版本中引入的所有策略都将设置为使用 NEW 行为。所有在更高版本中引入的策略都将被取消设置（除非 CMAKE_POLICY_DEFAULT_CMP<NNNN> 变量设置了默认值）。这实际上请求了给定 CMake 版本的首选行为，并告诉更新的 CMake 版本警告其新策略。

请注意，cmake_minimum_required(VERSION) 命令也会隐式调用 cmake_policy(VERSION)。

版本 3.31 中更改：与低于 3.10 版本的 CMake 的兼容性已弃用。在 CMake 3.31 及更高版本中，不指定至少 3.10 作为其策略版本（可选地通过 ...<max>）对 cmake_minimum_required(VERSION) 或 cmake_policy(VERSION) 的调用将产生弃用警告。

版本 3.27 中更改：与低于 3.5 版本的 CMake 的兼容性已弃用。在 CMake 3.27 及更高版本中，不指定至少 3.5 作为其策略版本（可选地通过 ...<max>）对 cmake_minimum_required(VERSION) 或 cmake_policy(VERSION) 的调用将产生弃用警告。

版本 3.19 中更改：与低于 2.8.12 版本的 CMake 的兼容性已弃用。在 CMake 3.19 及更高版本中，不指定至少 2.8.12 作为其策略版本（可选地通过 ...<max>）对 cmake_minimum_required(VERSION) 或 cmake_policy(VERSION) 的调用将产生弃用警告。

显式设置策略¶

cmake_policy(SET CMP<NNNN> NEW|OLD)¶

告诉 CMake 对给定策略使用 OLD 或 NEW 行为。依赖于给定策略旧行为的项目可以通过将策略状态设置为 OLD 来消除策略警告。或者，可以修复项目以使用新行为并将策略状态设置为 NEW。

注意

策略的 OLD 行为 根据定义已弃用，并可能在 CMake 的未来版本中删除。

检查策略设置¶

cmake_policy(GET CMP<NNNN> <variable>)¶

检查给定策略是否设置为 OLD 或 NEW 行为。如果策略已设置，则输出 <variable> 值将为 OLD 或 NEW，否则为空。

CMake 策略堆栈¶

CMake 保持策略设置在一个栈中，因此由 cmake_policy 命令做出的更改仅影响栈顶。对于每个子目录，都会自动管理一个新的策略栈条目，以保护其父目录和同级目录。CMake 还为 include() 和 find_package() 命令加载的脚本管理一个新的条目，除非使用 NO_POLICY_SCOPE 选项调用（另请参见策略 CMP0011）。cmake_policy 命令提供了一个接口来管理策略栈上的自定义条目。

cmake_policy(PUSH)¶: 在策略栈上创建一个新的条目。

cmake_policy(POP)¶: 删除由 cmake_policy(PUSH) 创建的最后一个策略栈条目。

每个 PUSH 都必须有一个匹配的 POP 来清除任何更改。这对于对策略设置进行临时更改很有用。对 cmake_minimum_required(VERSION)、cmake_policy(VERSION) 或 cmake_policy(SET) 命令的调用仅影响当前策略栈的顶部。

版本 3.25 中新增: block(SCOPE_FOR POLICIES) 命令提供了一种更灵活、更安全的方式来管理策略栈。离开块范围时会自动执行 pop 操作，因此无需在每个 return() 前面调用 cmake_policy(POP)。

# stack management with cmake_policy()
function(my_func)
  cmake_policy(PUSH)
  cmake_policy(SET ...)
  if (<cond1>)
    ...
    cmake_policy(POP)
    return()
  elseif(<cond2>)
    ...
    cmake_policy(POP)
    return()
  endif()
  ...
  cmake_policy(POP)
endfunction()

# stack management with block()/endblock()
function(my_func)
  block(SCOPE_FOR POLICIES)
    cmake_policy(SET ...)
    if (<cond1>)
      ...
      return()
    elseif(<cond2>)
      ...
      return()
    endif()
    ...
  endblock()
endfunction()

由 function() 和 macro() 命令创建的命令会在创建时记录策略设置，并在调用时使用预先记录的策略。如果函数或宏实现设置了策略，则更改会自动向上传播到调用者，直到到达最近的嵌套策略栈条目。

另请参阅¶

cmake_minimum_required()