企业官网建设流程全解析

• 构建工具
• 开发工具
• CLI

导读

CMP0178 是 CMake 3.31 引入的兼容性策略，核心变化是：由add_test()、ExternalData_Add_Test()、gtest_add_tests()/gtest_discover_tests()添加的测试，其命令行中的空参数（empty arguments）将不再被静默丢弃。具体涉及TEST_LAUNCHER、CROSSCOMPILING_EMULATOR两个目标属性中的空列表项，以及 GoogleTest 系列命令EXTRA_ARGS关键字后的空元素。读完本文，你将掌握该策略的触发场景、NEW/OLD 行为差异、cmake_policy设置方法，以及底层cmTestGenerator的实现原理，从而在升级 CMake 时正确处理空参数测试场景。

策略概述与引入版本

CMP0178 在 CMake 3.31 中引入，官方定义见 CMP0178.rst，其策略名称为"Test command lines preserve empty arguments"（测试命令行保留空参数）。在策略注册表中，它的记录位于 cmPolicies.h，注册参数为3, 31, 0, WARN，即：

• 引入于 CMake 3.31；
• 默认WARN级别——当策略未显式设置时，CMake 发出警告并使用OLD行为。

SELECT(POLICY, CMP0178, "Test command lines preserve empty arguments.", 3, 31, 0, WARN)

影响范围：三种添加测试的途径

该策略影响以下三种添加测试命令的途径：

• add_test()命令；
• ExternalData模块中的ExternalData_Add_Test()命令；
• GoogleTest模块中的gtest_add_tests()或gtest_discover_tests()命令。

对于gtest_add_tests()和gtest_discover_tests()，EXTRA_ARGS关键字之后传递的值中的空元素同样受此策略影响。

OLD 与 NEW 行为对比

OLD 行为（旧版默认）

OLD行为会静默丢弃以下场景中的空列表项：

• TEST_LAUNCHER目标属性中的空列表项；
• CROSSCOMPILING_EMULATOR目标属性中的空列表项；
• gtest_add_tests()和gtest_discover_tests()命令EXTRA_ARGS之后给出的空元素。

NEW 行为（新版推荐）

NEW行为保留上述所有空列表项：

• 保留TEST_LAUNCHER目标属性中的空列表项；
• 保留CROSSCOMPILING_EMULATOR目标属性中的空列表项；
• 保留gtest_add_tests()和gtest_discover_tests()命令EXTRA_ARGS之后的空元素。

简单地说：NEW 让空参数原样进入最终生成的测试命令行，OLD 则将其当作不存在。

为什么要保留空参数

在实际项目中，空参数并非无意义。考虑以下典型场景：

1. 测试启动器（launcher）带空槽位：例如TEST_LAUNCHER被设置为"launcher;arg1;;arg3"，中间的空元素可能代表一个"占位符"，需要在运行时被工具解析（如某些脚本约定参数索引位置）；
2. 交叉编译模拟器（emulator）参数拼接：CROSSCOMPILING_EMULATOR用于在交叉编译时模拟运行测试目标（如qemu-arm），其中某些参数列表的空项影响命令行解析结果；
3. GoogleTest 扩展参数：EXTRA_ARGS之后传入的空字符串，可能对应某个必须以位置对齐的测试参数。

OLD 行为将此类空项静默剔除，会导致生成的测试命令与开发者意图不一致，且没有任何提示，难以排查。CMP0178 的 NEW 行为通过保留空项修复了这一问题。

策略设置方法

与其他 CMake 策略一样，CMP0178 可通过cmake_policy或cmake_minimum_required设置，官方说明见 STANDARD_ADVICE.rst：

该策略在 CMake 3.31 中引入，可通过cmake_policy或cmake_minimum_required设置。若未设置，CMake 发出警告并使用OLD行为。

典型设置方式：

# 方法一：在调用受影响命令之前显式开启 NEW 行为 cmake_policy(SET CMP0178 NEW) # 方法二：通过 cmake_minimum_required 声明最低版本， # 若声明的版本 >= 3.31，则该目录内 CMP0178 自动为 NEW cmake_minimum_required(VERSION 3.31)

需要注意的是，OLD行为按定义已被弃用（见 DEPRECATED.rst），并可能在未来的 CMake 版本中被移除，因此新项目应直接使用NEW行为。

源码级实现原理

策略状态的读取与记录

在 cmAddTestCommand.cxx 中，add_test()命令解析时读取当前策略状态，并把它记录到测试对象上：

// 旧式签名（add_test(<name> <command> ...)）： cmPolicies::PolicyStatus cmp0178 = mf.GetPolicyStatus(cmPolicies::CMP0178); ... test->SetCMP0178(cmp0178);

// 新式签名（add_test(NAME <name> COMMAND <command> ...)）： cmPolicies::PolicyStatus cmp0178 = mf.GetPolicyStatus(cmPolicies::CMP0178); ... test->SetCMP0178(cmp0178);

这里通过cmMakefile::GetPolicyStatus(cmPolicies::CMP0178)读取策略状态，并通过cmTest::SetCMP0178()将状态与测试绑定，供后续生成阶段使用。

测试命令行的生成：launcher 与 emulator 的拼接

真正决定空参数是否保留的代码位于 cmTestGenerator.cxx 的GenerateCommand()函数中（约 第 230-288 行）。核心逻辑如下：

auto addLauncher = & { cmValue launcher = target->GetProperty(propertyName); if (!cmNonempty(launcher)) { return; } auto const propVal = ge.Parse(*launcher)->Evaluate(this->LG, config); cmList launcherWithArgs(propVal, cmList::ExpandElements::Yes, cmp0178 == cmPolicies::NEW ? cmList::EmptyElements::Yes : cmList::EmptyElements::No); ... };

可以看到，解析 launcher 属性时，是否保留空元素完全取决于策略状态：

• cmp0178 == NEW→cmList::EmptyElements::Yes（保留空项）；
• 否则（OLD）→cmList::EmptyElements::No（丢弃空项）。

两个属性按以下顺序被处理：

// Prepend with the test launcher if specified. addLauncher("TEST_LAUNCHER"); // Prepend with the emulator when cross compiling if required. if (cmp0158 != cmPolicies::NEW || this->LG->GetMakefile()->IsOn("CMAKE_CROSSCOMPILING")) { addLauncher("CROSSCOMPILING_EMULATOR"); }

即：先拼接TEST_LAUNCHER，再在交叉编译场景下拼接CROSSCOMPILING_EMULATOR，最终依次输出 launcher 可执行文件、launcher 参数、emulator、emulator 参数、测试可执行文件及其参数。

WARN 模式下的兼容性警告

当策略状态为WARN时（即未显式设置且按OLD行为运行），代码会对比"丢弃空项"与"保留空项"两种解析结果，若两者不一致，则发出 CMP0178 警告：

if (cmp0178 == cmPolicies::WARN) { cmList argsWithEmptyValuesPreserved( propVal, cmList::ExpandElements::Yes, cmList::EmptyElements::Yes); if (launcherWithArgs != argsWithEmptyValuesPreserved) { this->LG->GetMakefile()->IssuePolicyWarning( cmPolicies::CMP0178, cmStrCat("The ", propertyName, " property of target '", target->GetName(), "' contains empty list items. Those empty items are " "being silently discarded to preserve backward " "compatibility.")); } }

警告信息明确提示：目标某属性包含空列表项，为保持向后兼容这些空项将被静默丢弃。这帮助用户在升级到 3.31 后第一时间发现"空参数丢失"问题。

测试对象的策略绑定

cmTest类保存策略状态，相关定义见 cmTest.h 与 cmTest.cxx。当add_test()以旧式签名调用时，若命令中携带内部关键字__CMP0178（位于参数末尾），则直接依据其后的NEW/OLD/其他值确定策略状态，否则回落到mf.GetPolicyStatus(cmPolicies::CMP0178)，见 cmAddTestCommand.cxx 第 40-58 行。该机制是生成器表达式求值后cmTestGenerator生成 CTest 脚本时读取策略的依据。

典型场景示例

示例 1：TEST_LAUNCHER 中的空参数

cmake_minimum_required(VERSION 3.31) # CMP0178 自动为 NEW add_executable(my_app main.c) # launcher 列表中存在空项（第二个位置为空） set_property(TARGET my_app PROPERTY TEST_LAUNCHER "wrap.py;;--mode=fast") add_test(NAME my_test COMMAND my_app --do-something)

在NEW行为下，生成的测试命令行等价于：

wrap.py "" --mode=fast /path/to/my_app --do-something

空参数""会被保留并作为独立参数传递给测试启动器；而在OLD行为下，该空项会被丢弃，命令行变成：

wrap.py --mode=fast /path/to/my_app --do-something

对于依赖参数位置（例如wrap.py期望第二个参数是空占位符）的启动器，两种行为会产生截然不同的运行结果。

示例 2：交叉编译模拟器

cmake_minimum_required(VERSION 3.31) add_executable(firmware main.c) # 交叉编译时用 qemu 模拟运行，模拟器参数中带空项 set_property(TARGET firmware PROPERTY CROSSCOMPILING_EMULATOR "qemu-arm;-L;--;")

启用NEW后，空项会被保留，模拟器命令行与开发者设定的参数列表完全一致；而在OLD行为下空项被剔除，可能导致模拟器参数错位。

示例 3：GoogleTest 的 EXTRA_ARGS

include(GoogleTest) gtest_add_tests( TARGET my_unit_tests EXTRA_ARGS --gtest_filter=Suite.* "" --shuffle )

NEW行为保留EXTRA_ARGS之后的空元素，测试过滤器后的空参数会原样传给测试可执行文件；OLD行为则会将其丢弃。

策略设置建议与注意事项

1. 新项目：直接使用cmake_minimum_required(VERSION 3.31)或cmake_policy(SET CMP0178 NEW)，让空参数语义始终明确；
2. 存量项目升级：若测试涉及TEST_LAUNCHER、CROSSCOMPILING_EMULATOR或 GoogleTestEXTRA_ARGS，升级到 3.31 后应关注 WARN 模式下的 CMP0178 警告，确认旧行为是否依赖"空项被丢弃"这一隐含语义；
3. 设置位置：cmake_policy必须在调用add_test()、ExternalData_Add_Test()、gtest_add_tests()、gtest_discover_tests()之前设置，策略按目录作用域生效；
4. 未来兼容性：OLD行为已被弃用，可能在后续版本中被移除（参见 DEPRECATED.rst），建议尽早迁移到NEW。

总结

CMP0178 是 CMake 3.31 中一项"行为修正型"策略：它结束了TEST_LAUNCHER、CROSSCOMPILING_EMULATOR属性及 GoogleTestEXTRA_ARGS中空参数被静默丢弃的历史，通过cmTestGenerator在生成 CTest 测试脚本时按策略状态决定cmList是否保留空元素，并在 WARN 模式下给出明确提示。对依赖参数位置语义的测试启动器、交叉编译模拟器以及 GTest 参数对齐场景，本策略直接决定了生成的测试命令行是否符合开发者预期。升级至 CMake 3.31 后，建议统一启用NEW行为，以获取清晰、可预期的空参数传递语义。

• 构建工具
• 开发工具
• CLI