CMake 策略 CMP0223 详解:空路径不再被视为任何路径的前缀
CMake 策略 CMP0223 详解:空路径不再被视为任何路径的前缀
导读
CMake 4.5 引入的 CMP0223 策略用于修正路径前缀判定的边界语义:在 NEW 行为下,空路径不再被认为是任意路径(包括空路径自身)的前缀。本文以 Help/policy/CMP0223.rst 为骨架,结合 cmCMakePathCommand.cxx、cmGeneratorExpressionNode.cxx、cmConditionEvaluator.cxx 的底层实现以及 Tests/RunCMake/CMP0223 的测试用例,全面讲解该策略的产生背景、OLD/NEW 行为差异、受影响的三个判定入口(cmake_path(IS_PREFIX)、$<PATH:IS_PREFIX> 生成器表达式、if() 的 PATH_IS_PREFIX 操作符)、警告与迁移方式,帮助开发者在升级到 CMake 4.5+ 后正确应对空路径前缀的语义变化。
策略概述:它解决什么问题
该策略的标题是 "An empty path is not a prefix of any path."(空路径不是任何路径的前缀),于 CMake 4.5 版本(versionadded)引入,参见 CMP0223.rst 第 4 行。
问题产生的根源在于:在 CMP0223 出现之前,以下三个路径前缀判定入口会将空路径视为所有路径的前缀,包括空路径自身:
cmake_path(IS_PREFIX)子命令;$<PATH:IS_PREFIX>生成器表达式;if()命令的PATH_IS_PREFIX操作符(注意:该操作符与 CMP0222 同期在 4.5 中引入,本身没有历史行为,但它遵循 CMP0223,以便在任意策略状态下与cmake_path(IS_PREFIX)保持一致)。
导致这一行为出错的典型场景是:一个前缀因为变量被设置为空值,或生成器表达式实参展开后为空而变成空路径,此时本应被拒绝的前缀检查却意外通过了。换句话说,空路径既不是任何路径的真实前缀,把 "某路径以空串开头" 当成真命题会让 IS_PREFIX 的语义失真。
OLD 与 NEW 行为对照
按照 CMP0223.rst 第 19-21 行的定义:
| 行为 | 空路径是否为任意路径(含空路径自身)的前缀 |
|---|---|
OLD |
是(true) |
NEW |
否(false),空路径不是任何路径的前缀 |
策略默认的警告/行为规则由 include/STANDARD_ADVICE.rst 定义:CMP0223 引入于 CMake 4.5;可通过 cmake_policy() 或 cmake_minimum_required() 显式设置;如果未设置,CMake 会发出警告(warns)并采用 OLD 行为。
此外 include/DEPRECATED.rst 明确指出:策略的 OLD 行为按定义属于已弃用(deprecated)状态,可能在未来的 CMake 版本中被移除。因此升级后应主动将策略设为 NEW,而非长期依赖 OLD。
三个判定入口的语义与底层实现
cmake_path(IS_PREFIX):空前缀判定
cmake_path(IS_PREFIX) 子命令的入口位于 cmCMakePathCommand.cxx(HandleIsPrefixCommand),其子命令注册表见同文件 L945-L972。核心计算逻辑为:
bool const isPrefix =
prefix.IsPrefix(value) || IsPrefixCMP0223(prefix, status.GetMakefile());
即结果 = 常规前缀判断 prefix.IsPrefix(value) 或 由策略决定的空路径回退判断。策略相关函数 IsPrefixCMP0223 的实现是:
// CMP0223: an empty path used to be a prefix of every path.
bool IsPrefixCMP0223(cmCMakePath const& prefix, cmMakefile& mf)
{
if (!prefix.IsEmpty()) {
return false;
}
switch (mf.GetPolicyStatus(cmPolicies::CMP0223)) {
case cmPolicies::WARN:
mf.IssuePolicyWarning(cmPolicies::CMP0223);
CM_FALLTHROUGH;
case cmPolicies::OLD:
return true;
case cmPolicies::NEW:
break;
}
return false;
}
可以看到:
- 前缀非空时,该函数直接返回
false,不触发任何策略逻辑——非空前缀的行为在 OLD/NEW 下完全一致; - 前缀为空时,
WARN状态下会发出 CMP0223 策略警告并回落到OLD(返回true);OLD直接返回true;只有NEW返回false,从而让空前缀判定失败。
$PATH:IS_PREFIX 生成器表达式:空实参展开
生成器表达式 $<PATH:IS_PREFIX,...> 的求值位于 cmGeneratorExpressionNode.cxx。由于生成器表达式实参可能展开为空字符串(例如变量为空、表达式为空),空路径很容易在这里产生,其实现与 cmake_path 版本同构:
// CMP0223: an empty path used to be a prefix of every path.
bool IsPrefixCMP0223(cmCMakePath const& prefix, cm::GenEx::Evaluation* eval)
{
if (!prefix.IsEmpty()) {
return false;
}
cmLocalGenerator const* const lg = eval->Context.LG;
switch (lg->GetPolicyStatus(cmPolicies::CMP0223)) {
case cmPolicies::WARN:
lg->IssuePolicyWarning(cmPolicies::CMP0223, {}, {}, eval->Backtrace);
CM_FALLTHROUGH;
case cmPolicies::OLD:
return true;
case cmPolicies::NEW:
break;
}
return false;
}
在 NEW 状态下,$<PATH:IS_PREFIX,,/a/b> 求值为 0;在 OLD 状态下为 1。这一细节在 CMP0223-genex-common.cmake 与对应的 OLD/NEW 检查脚本中得到验证(详见下文测试章节)。
if() 的 PATH_IS_PREFIX 操作符
if() 命令的 PATH_IS_PREFIX 操作符在 cmConditionEvaluator.cxx 中求值。它由 CMP0222 引入(策略表中见 cmPolicies.h),本身没有更早的历史行为,但特意跟随 CMP0223,使得三个入口在任意策略状态下结论一致。其核心逻辑为:
cmCMakePath const prefix{ *lhs };
auto const result = prefix.IsPrefix(cmCMakePath{ *rhs }) ||
IsPrefixCMP0223(prefix, this->Makefile);
注意:PATH_IS_PREFIX 操作符是否被识别为操作符,受 CMP0222 控制(OLD/未设置时按字符串处理并给出 CMP0222 警告,参见 cmConditionEvaluator.cxx);而其中空路径前缀的最终语义则由 CMP0223 决定。两者是"操作符启用"与"空前缀语义"两个正交维度,测试用例 CMP0223-if-WARN.cmake 展示了这一组合用法:
cmake_policy(SET CMP0222 NEW)
# CMP0223 deliberately not set, so the warning fires and OLD behavior applies.
if(NOT "" PATH_IS_PREFIX "/a/b")
message(SEND_ERROR "empty prefix is not a prefix of '/a/b' under WARN")
endif()
该用例显式设置 CMP0222 NEW 而故意不设置 CMP0223,于是 CMP0223 的警告触发、OLD 行为生效,"" PATH_IS_PREFIX "/a/b" 为真(进而 NOT 后触发错误分支预期失败,证明 WARN 下空前缀判定仍为真)。
源码中的策略注册
CMP0223 在 cmPolicies.h 的策略表中注册,其声明为:
SELECT(POLICY, CMP0223, "An empty path is not a prefix of any path.", 4, 5, \
0, WARN)
各字段含义:策略标识 CMP0223;一句话描述;引入版本主版本号 4、次版本号 5;未知字段 0;警告模式 WARN(即未显式设置时发出警告并采用 OLD 行为)。该表中同一批次的相邻策略(如 CMP0220–CMP0226)均为 4.5 引入,共同构成该版本的策略变更集合。
测试验证:OLD/NEW/WARN 三态行为
策略仓库在 Tests/RunCMake/CMP0223 目录下提供了一组完整的 RunCMake 测试,覆盖三种策略状态:
cmake_path(IS_PREFIX) 测试
CMP0223-NEW.cmake(设置 CMP0223 NEW)断言:
- 空前缀对
/a/b:output必须为假,否则SEND_ERROR; - 空前缀对空路径:
output必须为假; NORMALIZE选项不改变结论——因为归一化空路径仍为空;- 非空前缀
/a对/a/b:不受影响,仍为真。
CMP0223-OLD.cmake(设置 CMP0223 OLD)断言相反:空前缀对 /a/b 与空路径都为真。
$PATH:IS_PREFIX 生成器表达式测试
CMP0223-genex-common.cmake 生成 result.txt:
file(GENERATE OUTPUT "result.txt" CONTENT
"empty=$<PATH:IS_PREFIX,,/a/b> normalize=$<PATH:IS_PREFIX,NORMALIZE,,/a/b> nonempty=$<PATH:IS_PREFIX,/a,/a/b>")
对应的检查脚本断言:
- CMP0223-genex-NEW-check.cmake:
empty=0 normalize=0 nonempty=1; - CMP0223-genex-OLD-check.cmake:
empty=1 normalize=1 nonempty=1。
这精确验证了:NEW 下空前缀(含 NORMALIZE 后的空前缀)判定为 0,非空前缀保持 1;OLD 下空前缀判定为 1。同时该组测试还包含 -WARN 变体(CMP0223-genex-WARN.cmake、CMP0223-genex-WARN-stderr.txt)以及 if 命令的 CMP0223-if-WARN.cmake 与 CMP0223-if-WARN-stderr.txt,用于校验 WARN 状态下的警告输出与行为回退。
典型踩坑场景演示
NEW 行为下,以下代码会按预期拒绝空前缀:
cmake_policy(SET CMP0223 NEW)
set(prefix "") # 变量被清空
cmake_path(IS_PREFIX prefix "/a/b" output) # output = 0(NEW)
if(output)
message(SEND_ERROR "empty prefix is a prefix of '/a/b' under NEW")
endif()
# 生成器表达式实参展开为空同样被拒绝
file(GENERATE OUTPUT "result.txt" CONTENT
"empty=$<PATH:IS_PREFIX,,/a/b>") # empty=0(NEW)
而 OLD 行为下,同样的输入会得到 output = 1 / empty=1,从而让"为拒绝空前缀而写的检查"失效——这正是该策略要消除的语义陷阱。
迁移建议与最佳实践
-
显式声明策略:在项目
CMakeLists.txt顶部使用cmake_minimum_required(VERSION 4.5)会自动将 CMP0223 置为 NEW(同版本策略随最低版本要求生效);也可以在设置cmake_minimum_required后单独执行cmake_policy(SET CMP0223 NEW)进行显式控制。未设置时 CMake 会发出警告并沿用 OLD 行为。 -
升级前自查:搜索项目中是否依赖"空路径是任意路径前缀"的隐式行为,例如
cmake_path(IS_PREFIX ...)、$<PATH:IS_PREFIX,...>、if(... PATH_IS_PREFIX ...)中可能展开为空串的变量或生成器表达式实参。若确实依赖旧语义,应在升级到 4.5+ 前修复逻辑,而不是长期停留在 OLD。 -
善用警告定位:WARN 状态下每个触发点都会输出 CMP0223 策略警告(源码中对应
IssuePolicyWarning,见 cmCMakePathCommand.cxx、cmGeneratorExpressionNode.cxx),可用于逐一排查受影响的判定点。 -
注意与 CMP0222 的协同:
if()的PATH_IS_PREFIX操作符由 CMP0222 引入并决定是否按操作符解析,空前缀语义才由 CMP0223 决定。若同时升级到 4.5,建议将两个策略一并显式设置为 NEW,避免"操作符启用但空前缀仍是旧语义"的混合状态。 -
警惕 OLD 的弃用风险:依据 include/DEPRECATED.rst,OLD 行为按定义已弃用,可能在未来版本移除,切勿以 OLD 作为长期方案。
延伸阅读
- 策略正文:Help/policy/CMP0223.rst
- 配套策略 CMP0222(引入
PATH_IS_PREFIX操作符):Help/policy/CMP0222.rst - 策略通用说明(OLD/NEW 机制与弃用约定):Help/policy/index.rst 与 Help/policy/include/DEPRECATED.rst
- 底层实现:
cmake_path(IS_PREFIX)见 cmCMakePathCommand.cxx,生成器表达式见 cmGeneratorExpressionNode.cxx,if 操作符见 cmConditionEvaluator.cxx,策略注册见 cmPolicies.h - 测试用例:Tests/RunCMake/CMP0223 目录下全部 OLD/NEW/WARN 变体