CMake 策略 CMP0223 详解:空路径不再被视为任何路径的前缀

原创2026-10-09 09:53:581,858 阅读
文章标签:开发工具构建工具跨平台测试

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>")

对应的检查脚本断言:

这精确验证了: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,从而让"为拒绝空前缀而写的检查"失效——这正是该策略要消除的语义陷阱。

迁移建议与最佳实践

  1. 显式声明策略:在项目 CMakeLists.txt 顶部使用 cmake_minimum_required(VERSION 4.5) 会自动将 CMP0223 置为 NEW(同版本策略随最低版本要求生效);也可以在设置 cmake_minimum_required 后单独执行 cmake_policy(SET CMP0223 NEW) 进行显式控制。未设置时 CMake 会发出警告并沿用 OLD 行为。

  2. 升级前自查:搜索项目中是否依赖"空路径是任意路径前缀"的隐式行为,例如 cmake_path(IS_PREFIX ...)、$<PATH:IS_PREFIX,...>、if(... PATH_IS_PREFIX ...) 中可能展开为空串的变量或生成器表达式实参。若确实依赖旧语义,应在升级到 4.5+ 前修复逻辑,而不是长期停留在 OLD。

  3. 善用警告定位:WARN 状态下每个触发点都会输出 CMP0223 策略警告(源码中对应 IssuePolicyWarning,见 cmCMakePathCommand.cxx、cmGeneratorExpressionNode.cxx),可用于逐一排查受影响的判定点。

  4. 注意与 CMP0222 的协同:if() 的 PATH_IS_PREFIX 操作符由 CMP0222 引入并决定是否按操作符解析,空前缀语义才由 CMP0223 决定。若同时升级到 4.5,建议将两个策略一并显式设置为 NEW,避免"操作符启用但空前缀仍是旧语义"的混合状态。

  5. 警惕 OLD 的弃用风险:依据 include/DEPRECATED.rst,OLD 行为按定义已弃用,可能在未来版本移除,切勿以 OLD 作为长期方案。

延伸阅读

登录后查看全文
CMake