CMake指令：mark_as_advanced

目录

1.简介

2.核心作用

3.使用示例

4.常见使用场景

5.注意事项

6.总结

相关链接

---

1.简介

        在 CMake 中，mark_as_advanced() 是一个用于控制变量在配置工具（如 CMake GUI、ccmake）中显示行为的命令。它的核心功能是将指定变量标记为 “高级变量”，使其在默认视图中隐藏，仅当用户主动切换到 “显示高级选项” 模式时才可见。

        基本语法：

mark_as_advanced([CLEAR|FORCE] <变量1> <变量2> ...)

• 参数说明：
  • <变量1> <变量2> ...：需要标记为高级的变量名称（多个变量用空格分隔）。
  • CLEAR（可选）：清除变量的 “高级” 标记，使其恢复为默认可见状态。
  • FORCE(可选，默认也时FORCE，不填写也是FORCE)，标记为高级变量名称

2.核心作用

CMake 项目中会产生大量变量（如编译选项、路径配置、第三方库信息等），其中部分变量是普通用户无需关心的（如内部调试参数、系统自动检测的路径）。mark_as_advanced() 的作用是：

• 简化配置界面：隐藏高级变量，减少普通用户的认知负担。
• 区分配置层级：让关键变量（如 BUILD_TESTING、CMAKE_INSTALL_PREFIX）保持可见，高级变量（如编译器细节、内部缓存值）默认隐藏。

3.使用示例

1.标记高级变量（默认隐藏）

假设项目中有一个仅用于开发者调试的变量 ENABLEABLE_DEBUG_LOG，普通希望普通用户修改，可将其标记为高级：

# 定义一个调试用的变量（缓存变量，允许用户通过 -D 或 GUI 修改）
set(ENABLE_DEBUG_LOG OFF CACHE BOOL "Enable用详细调试日志（仅开发者使用）")# 将其标记为高级变量（默认在 GUI 中隐藏）
mark_as_advanced(ENABLE_DEBUG_LOG)

在 CMake GUI 中：

• 默认情况下，ENABLEABLE_DEBUG_LOG 不会显示。
• 勾选 “Advanced” 选项后，该变量才会出现在配置列表中。

2.清除高级标记（恢复可见）

如果需要让某个已标记为高级的变量重新在默认视图中可见，可使用 CLEAR 选项：

# 假设之前已将 MY_VAR 标记为高级
mark_as_advanced(MY_VAR)# 现在需要恢复其可见性
mark_as_advanced(CLEAR MY_VAR)

3.批量标记多个变量

项目中可能有多个关联的高级变量（如第三方库的内部配置），可批量处理：

# 第三方库的路径变量（普通用户无需修改）
set(LIBFOO_INCLUDE_DIR "" CACHE PATH "libfoo 头文件路径")
set(LIBFOO_LIBRARY "" CACHE FILEPATH "libfoo 库文件路径")# 批量标记为高级变量
mark_as_advanced(LIBFOO_INCLUDE_DIR LIBFOO_LIBRARY)

4.常见使用场景

1.隐藏系统自动检测的变量

CMake 自动检测的系统信息（如 CMAKE_SYSTEM_NAME、CMAKE_C_COMPILER）通常默认被标记为高级，避免用户误修改。

2.内部调试 / 开发变量

仅开发者需要调整的参数（如 LOG_LEVEL、ENABLE_ASSERTIONS），标记为高级可减少普通用户的困惑。

3.第三方库的细节配置

查找第三方库时生成的变量（如 Boost_INCLUDE_DIR、Qt5_DIR），普通用户无需关心，标记为高级更合适。

5.注意事项

• 不影响变量功能：mark_as_advanced() 仅控制变量在配置工具中的显示，不改变变量的实际值或作用（变量仍可通过 -D<变量名>=<值> 命令行参数修改）。
• 核心变量不建议标记：项目关键配置变量（如 BUILD_SHARED_LIBS、CMAKE_BUILD_TYPE）应保持默认可见，方便用户调整。
• 尊重内置变量的默认设置：CMake 内置变量（如 CMAKE_INSTALL_PREFIX）已有预设的可见性，除非特殊需求，无需手动修改。

6.总结

        mark_as_advanced() 是优化 CMake 配置体验的实用工具，通过合理区分普通变量和高级变量，既能简化普通用户的配置流程，又能为高级用户保留必要的调整入口。在大型项目中，这一命令能有效提升配置界面的清晰度和易用性。

相关链接

• CMake 官网 CMake - Upgrade Your Software Build System
• CMake 官方文档：CMake Tutorial — CMake 4.1.0-rc4 Documentation
• CMake 源码：https://github.com/Kitware/CMake
• CMake 源码：CMake · GitLab
• 中文版基础介绍: CMake 入门实战 | HaHack
• wiki: Home · Wiki · CMake / Community · GitLab
• Modern CMake 简体中文版:  Introduction · Modern CMake