引言：当“施工规范”面临更新换代
在前面的章节中，我们的CMake“施工队长”已经身经百战：从图纸（Target）到交付（Install），从海外工程（交叉编译）到迎接各路监理（IDE集成），可谓十八般武艺样样精通。但不知道你有没有遇到过这样的场景：你升级了CMake的版本，希望能用上一些新特性，结果原本编译得好好的老项目突然冒出一大堆警告，甚至有些地方直接构建失败；或者你在团队协作中，有人用CMake 3.20写了一段脚本，你本地CMake 3.16却读出了完全不同的意思。
这就好比建筑行业的施工规范（GB标准）每隔几年就会更新：新版本可能规定“脚手架必须使用卡扣式连接而非传统的绑扎”，但你的老项目图纸明明还是按旧规范设计的。如果新规范一出台就强制所有老工地立即停工整改，那世界就乱套了。因此，需要一种机制来温和地、可控地引入新行为，同时保护存量项目——这就是CMake的策略（Policy）系统。
在这一节中，我们将翻开CMake这位“施工队长”的《内部管理手册》，搞懂它是如何处理新旧行为冲突的，以及如何优雅地升级你的“施工规范”。
一、CMake策略机制原理：新旧行为的切换控制
CMake的策略系统本质上是一套行为开关。每当CMake的开发者想要引入一个与旧版本不兼容的变更时（例如改变某个变量的解析规则、修正一个历史遗留的Bug、或改变默认的搜索路径），他们不会直接粗暴地修改全局行为，而是会发布一个新的策略（Policy）。
1.1 策略的身份证：CMPxxxx
每个策略都有一个唯一的编号，格式为 CMP 后跟四位数字，例如 CMP0048、CMP0100。每个策略对应一对行为：
- OLD行为（Legacy Behavior）： 保持与旧版本兼容的原有逻辑。
- NEW行为（Modern Behavior）： 采用新版本的修正后逻辑。
你可以把每个策略想象成一个墙上的双控开关：OLD 是左边的老线路，NEW 是右边的新线路。CMake不会擅自帮你拨动开关，而是根据项目的“施工规范版本声明”（即 cmake_minimum_required）来决定默认拨向哪一边。
1.2 为什么需要策略系统
假设没有策略系统，CMake 3.28直接修改了某个命令的默认行为。那么所有在CMake 3.10时代编写的项目，在开发者升级CMake工具链后，可能会无声无息地产生错误结果，甚至编译出行为异常的程序。这对于强调可重复构建（Reproducible Build）的C++生态来说是灾难性的。
策略系统提供了一条缓冲带：
- 保护存量项目： 老项目通过较低的
cmake_minimum_required版本，自动锁定旧行为，确保构建结果不变。 - 允许新项目受益： 新项目通过较高的版本声明，自动启用新行为，享受修正后的正确逻辑。
- 提供显式控制： 对于想要逐步升级的老项目，开发者可以逐一手动调整特定策略，而不用一次性面对所有变更。
1.3 查看当前策略状态
CMake提供了一个内置命令来查看策略信息。你可以通过以下命令列出所有已知的策略：
cmake --help-policies如果你想查看某个具体策略的说明，可以加上策略编号：
cmake --help-policy CMP0048输出会详细解释该策略的引入版本、OLD行为、NEW行为以及为何引入。
二、策略设置与兼容性处理：cmake_policy命令
虽然 cmake_minimum_required 可以批量设置策略默认值，但在实际工程中，我们有时需要更精细的控制。例如：项目主体仍想保持旧规范，但某个新引入的子模块需要新规范；或者反过来，你想在全局启用新规范，但某个祖传代码片段暂时无法适配。
这时就需要用到 cmake_policy 命令。
2.1 直接设置策略状态
最基础的用法是显式将某个策略设为 NEW 或 OLD：
# 强制使用 project() 命令设置版本变量的新行为（CMP0048）
cmake_policy(SET CMP0048 NEW)
# 暂时回到旧行为，避免某个第三方库报错
cmake_policy(SET CMP0054 OLD)这种设置会影响当前作用域及其子作用域（例如后续的子目录、函数调用等），直到被显式覆盖或遇到 cmake_policy(POP)。
2.2 策略栈：PUSH与POP
cmake_policy 内部维护了一个策略栈（Policy Stack）。你可以把当前所有策略的状态“压栈”保存，然后大胆修改，用完后再“弹栈”恢复。这在编写可复用的CMake模块或函数时尤为重要：
function(my_complex_function)
# 保存调用者的策略状态
cmake_policy(PUSH)
# 在本函数内强制使用新策略
cmake_policy(SET CMP0091 NEW)
# ... 执行一些依赖新策略的逻辑 ...
add_library(foo STATIC src/foo.cpp)
# 恢复调用者的策略状态，避免污染外部环境
cmake_policy(POP)
endfunction()这种“保存-修改-恢复”的模式，类似于在函数开头记录全局状态，在结尾还原，是编写无副作用模块的黄金法则。
2.3 查询策略当前值
你可以用 GET 子命令查询某个策略当前处于 NEW 还是 OLD：
cmake_policy(GET CMP0048 my_policy_status)
message(STATUS "CMP0048 is currently: ${my_policy_status}")这对于调试非常有用，特别是当你接手一个祖传项目，不确定某个诡异行为是否由策略设置引起时。
2.4 兼容性警告的处理
当你使用了一个较新版本的CMake，但 cmake_minimum_required 声明的版本较低时，CMake可能会在配置阶段输出警告：
CMake Warning (dev) at CMakeLists.txt:5 (project):
Policy CMP0048 is not set: project() command manages VERSION variables.
Run "cmake --help-policy CMP0048" for policy details. Use the cmake_policy
command to set the policy and suppress this warning.这类警告不是错误，但非常烦人。处理策略通常有三种方式：
- 升级版本声明： 如果项目整体可以升级，直接提高
cmake_minimum_required（推荐）。 - 显式设置策略： 在
CMakeLists.txt开头添加cmake_policy(SET CMPxxxx NEW)。 - 静默兼容（不推荐长期用）： 显式设为
OLD，保持旧行为，但会积累技术债务。
三、cmake_minimum_required与策略栈：版本与策略的绑定
如果把策略系统比作施工规范，那么 cmake_minimum_required 就是项目门口挂着的资质等级牌。它不仅告诉CMake“这个项目至少需要哪个版本的队长来管理”，更重要的是，它隐式地决定了所有策略开关的默认位置。
3.1 版本声明如何影响策略
当你在 CMakeLists.txt 的最开头写下：
cmake_minimum_required(VERSION 3.16)CMake会做两件事：
- 版本检查： 如果当前CMake版本低于3.16，直接报错退出。
- 策略归位： 将所有在3.16及之前版本引入的策略，默认设置为
NEW；而对于3.16之后才引入的策略（例如3.20引入的CMP0120），则保持未设置状态（CMake会根据具体情况给出警告或采用兼容行为）。
换句话说，cmake_minimum_required(VERSION 3.16) 等价于CMake在内部做了一个批量操作：“所有3.16之前已知的问题修正，默认都按新规范来；3.16之后的新规范，等以后升级版本再说。”
3.2 策略的继承与隔离
CMake的策略状态是分层继承的，其规则如下：
- 目录级（Directory Scope）： 每个
CMakeLists.txt及其包含的子目录都会继承父目录的策略状态。 - 函数级（Function Scope）： 函数内部继承调用处的策略状态，但可以通过
cmake_policy(PUSH/POP)或cmake_policy(SET)局部覆盖。 - 模块级（Module Scope）： 通过
include()引入的模块也继承当前目录的策略。
这意味着，如果你在根目录设置了 cmake_minimum_required(VERSION 3.20)，那么通过 add_subdirectory(third_party) 引入的子项目默认也会“看到”这些策略设置。但如果第三方库自己的 CMakeLists.txt 开头又写了一句 cmake_minimum_required(VERSION 3.10)，它会在其目录内部将策略回退到3.10对应的默认值，而不会影响父项目。
3.3 cmake_policy(VERSION)的妙用
除了 cmake_minimum_required，你还可以用 cmake_policy(VERSION) 来批量设置策略：
# 将当前目录及以下的策略默认值设为3.19对应的状态
cmake_policy(VERSION 3.19)这与 cmake_minimum_required 的区别在于：它不会进行版本检查。即使当前CMake是3.25，你也可以调用 cmake_policy(VERSION 3.19) 来“假装”自己是3.19的行为模式。这在编写需要兼容多个CMake版本的复杂模块时偶尔有用，但大多数情况下，建议还是使用 cmake_minimum_required，因为它更清晰、更安全。
四、新旧行为迁移指南：升级CMake版本的步骤
了解了策略系统的原理和控制方法后，真正的实战问题来了：你的项目目前声明 cmake_minimum_required(VERSION 3.10)，但团队决定升级到CMake 3.25，以使用一些Modern CMake的新特性。你该怎么做才能平稳过渡？
4.1 第一步：提高版本声明，观察警告
先将根目录的 cmake_minimum_required 修改为目标版本：
cmake_minimum_required(VERSION 3.25)然后运行配置：
cmake -B build -S .此时CMake可能会输出大量警告（通常是 CMake Warning (dev)），告诉你有哪些策略从“未设置”变成了“NEW”，或者哪些旧写法不再被推荐。仔细阅读这些警告，它们是最直接的迁移路线图。
4.2 第二步：逐个评估受影响的策略
不要一看到警告就慌。打开CMake文档（或执行 cmake --help-policy CMPxxxx），确认该策略的 NEW 行为具体是什么。例如：
CMP0091：在MSVC下，NEW行为会让CMAKE_MSVC_RUNTIME_LIBRARY变量控制运行时库，而不是旧模式下的编译器标志篡改。这通常是好事。CMP0048：NEW行为要求project()命令的版本号会被赋值给PROJECT_VERSION等变量。如果你的代码之前手动设置了这些变量，可能会冲突。
4.3 第三步：分而治之，先主干后分支
对于大型项目，不建议一次性全局升级。可以采用以下策略：
- 根目录先升级： 将主项目的
cmake_minimum_required提高，处理完主项目的警告。 - 隔离第三方库： 如果某些
add_subdirectory引入的外部项目还未适配，让它们保持自己的低版本声明。CMake会在它们的子目录内自动回退策略，互不干扰。 - 显式桥接： 如果某个祖传模块实在改不动，但主项目需要新策略，可以在模块内部用
cmake_policy(SET CMPxxxx OLD)作为临时兼容层，并加上TODO注释。
4.4 第四步：利用CI进行回归测试
升级策略后，构建结果在二进制层面应该与之前完全一致（除非你依赖的正是旧行为的Bug）。因此，务必在升级后跑一遍完整的测试套件：
cmake --build build
ctest --test-dir build --output-on-failure如果测试通过，说明 NEW 行为没有破坏你的业务逻辑。
4.5 常见“坑点”速查
在迁移过程中，以下几个策略是最常遇到“水土不服”的：
- CMP0054：
NEW行为下，if()语句中对字符串的解析更严格，不再把变量内容当成变量名二次解析。这通常会修复一些诡异的条件判断Bug。 - CMP0077：
option()命令的NEW行为下，如果变量已被设为普通变量，则不再被option()覆盖。这对于依赖-DFOO=ON命令行传参的项目影响巨大。 - CMP0091（MSVC专属）： 影响MSVC运行时库的选择方式。升级到
NEW后，应改用CMAKE_MSVC_RUNTIME_LIBRARY标准变量。 - CMP0135（CMake 3.24+）：
ExternalProject_Add的URL下载默认使用下载文件的文件名，而不是重命名为download。这会影响一些基于哈希校验的构建缓存。
小结
CMake的策略系统就像是施工行业里新老规范的缓冲带与转换器。它既保证了新项目能享受最新、最安全的构建行为，又呵护着海量存量项目的稳定性。
在本节中，我们搞懂了四个核心问题：
- 策略是什么： 每个
CMPxxxx都是一个新旧行为开关，CMake通过它优雅地引入不兼容变更。 - 如何手动控制： 通过
cmake_policy(SET ...)、PUSH、POP可以在局部作用域精细调整行为，避免污染全局。 - 版本声明的深层含义：
cmake_minimum_required不只是版本检查，更是一键批量设置策略默认值的“规范等级牌”。 - 如何安全升级： 提高版本声明 → 阅读警告 → 逐个评估 → 分模块迁移 → CI回归验证，是平稳过渡的标准路径。
下一次，当你升级CMake后看到满屏的 Policy CMPxxxx is not set 警告时，别再感到恐惧。那是CMake在礼貌地向你递送一份升级路线图——而你，已经学会了如何阅读它。
没有回复内容