当前位置：首页 > news >正文

CMake 策略 CMP0077：子目录中 option() 与父目录同名变量的行为及规避方法

news 2026/3/27 6:23:19

CMake 策略 CMP0077：子目录中 option() 与父目录同名变量的行为及规避方法

概述

在层次化 CMake 工程中，父工程常通过set()为子工程预先设定功能开关；子工程（如第三方依赖、子模块）又常用option()声明同名缓存选项。二者同名时，实际生效值受策略 CMP0077约束。若未显式采用 NEW 行为，在部分 CMake 版本下子目录中的option()可能覆盖父级已设置的普通变量，导致条件编译结果与预期不符，最终在链接阶段出现未定义符号等现象。

本文说明 CMP0077 的语义差异，并给出子工程与顶层工程均可采用的通用写法，适用于任意多目录 CMake 项目。

1. 适用场景与问题成因

常见结构如下：

顶层工程在add_subdirectory()之前执行set(ENABLE_FEATURE ON)（或OFF），意图向子目录传递默认开关。
子目录的CMakeLists.txt中存在option(ENABLE_FEATURE "说明" OFF)，为独立构建该子目录时提供可配置项。

当上述名称一致时，option()是否会改写当前作用域中已由set()赋值的变量，取决于CMP0077取 OLD 还是 NEW。OLD 行为下，可能将父级传入的ON重置为option的默认值，从而使if(ENABLE_FEATURE)控制的源文件未参与编译，后续链接缺少对应符号。

该问题与具体业务代码无关，属于 CMake 变量与缓存选项的交互规则问题；不同构建机上的 CMake 版本、缓存是否已存在该选项等因素，会导致表现不一致。

2. 策略 CMP0077 说明

CMake 3.13 引入策略CMP0077，规范option()与已存在普通变量同名时的行为。

策略取值	行为概要
OLD	在缓存中尚无该选项（或相关条件满足）时，`option()`可能清除或覆盖当前作用域中的同名普通变量，效果上类似将父级`set(ENABLE_FEATURE ON)`恢复为`option`声明的默认值（如`OFF`）。
NEW	若同名普通变量已存在，`option()`不修改该变量，也不据此写入缓存；父级通过`set()`传入的值得以保留。

未在工程中设置 CMP0077 时，行为由cmake_minimum_required所隐含的默认策略决定；较旧策略版本下往往为 OLD，从而易出现子目录覆盖父目录意图的情况。

3. 典型表现

父目录已打开某功能开关，但生成的目标文件中未包含该功能对应的目标文件。
链接时报错：undefined reference/undefined symbol，符号来自本应被条件编译进库的翻译单元。
在不同机器、不同 CI 作业或有无历史CMakeCache.txt时，同一套脚本出现「一处通过、另一处失败」的差异。

出现上述现象时，可检查子目录是否对父级已set的变量再次调用option()，并结合 CMP0077 与缓存状态排查。

4. 子工程侧：条件化声明 option

原则：仅在变量尚未定义时再调用option()，避免在父级已传入普通变量时再次声明同名选项并触发 OLD 语义下的覆盖。

不推荐（子目录中无条件option，在 CMP0077 OLD 下存在覆盖风险）：

option(ENABLE_FEATURE "Enable optional feature" OFF) if(ENABLE_FEATURE) list(APPEND LIB_SOURCES optional.cc) endif() add_library(example_lib STATIC ${LIB_SOURCES})

5. 顶层工程侧：显式策略 NEW

在首次add_subdirectory()引入相关子目录之前，于顶层将 CMP0077 设为 NEW，可从策略层避免option()覆盖已存在的普通变量：

cmake_minimum_required(VERSION 3.13) project(ExampleTop) set(ENABLE_FEATURE ON) cmake_policy(SET CMP0077 NEW) add_subdirectory(third_party/some_lib)

即使子目录仍写有option(ENABLE_FEATURE ... OFF)，在 NEW 语义下也不会覆盖顶层set(ENABLE_FEATURE ON)所设普通变量。

可与第四节中的「条件化option()」同时使用，作为互补措施。

6. 做法对照与选择建议

措施	作用范围	说明
`if(NOT DEFINED …) option(…) endif()`	子目录	不依赖策略版本即可避免在变量已定义时重复声明；利于第三方库可被顶层与独立构建两种方式使用。
`cmake_policy(SET CMP0077 NEW)`	顶层（在相应`add_subdirectory`前）	统一工程内`option()`与已有普通变量的交互规则；要求 CMake ≥ 3.13。

建议：子目录库采用条件化option()，便于作为子模块被任意父工程集成；应用或聚合工程在可控前提下可设置 CMP0077 NEW，并与最低 CMake 版本要求对齐。

7. 版本与文档

CMP0077自 CMake 3.13 起提供；使用cmake_policy(SET CMP0077 NEW)时，cmake_minimum_required通常需不低于 3.13（或与项目实际最低版本策略一致）。
具体 OLD/NEW 的完整条件以官方文档为准；缓存中已存在的OPTION类型变量也会影响行为，排查时可结合CMakeCache.txt与cmake --trace-expand等手段。