【CMake】option() 命令详解

CMake option 命令详解

option 是 CMake 中用于定义布尔开关的命令，允许用户在配置阶段通过命令行或 GUI 工具（如 cmake-gui）控制项目的编译选项。

基本语法：

option(<variable_name> "<help_text>" [initial_value])

• <variable_name>：选项变量名（全大写约定）
• <help_text>：选项的描述文本（显示在 GUI 工具中）
• [initial_value]：初始值（ON/OFF），默认 OFF

核心特性：

1. 定义缓存变量
   选项值会被存入 CMakeCache.txt，后续配置将记住用户的选择。
2. 布尔值限制
   变量值只能是 ON 或 OFF（不区分大小写）。
3. 默认值保护
   若缓存中已存在该变量（如用户通过 -D 设置过），option() 会忽略默认值，优先使用缓存值。

使用示例

示例 1：基础用法

# CMakeLists.txt
option(ENABLE_DEBUG "Enable debug mode" OFF)

if(ENABLE_DEBUG)
    message(STATUS "Debug mode activated")
    add_definitions(-DDEBUG_MODE)
else()
    message(STATUS "Debug mode disabled")
endif()

用户配置方式：

cmake -DENABLE_DEBUG=ON ..  # 启用调试
cmake -DENABLE_DEBUG=OFF .. # 显式关闭（默认值可省略）

示例 2：控制子目录包含

option(BUILD_TESTS "Build test programs" ON)

if(BUILD_TESTS)
    message(STATUS "Building tests")
    add_subdirectory(tests)
else()
    message(STATUS "Skipping tests")
endif()

示例 3：组合选项逻辑

option(USE_OPENMP "Enable OpenMP parallelization" OFF)
option(USE_AVX2   "Enable AVX2 optimizations" OFF)

if(USE_OPENMP)
    find_package(OpenMP REQUIRED)
    target_link_libraries(myapp PUBLIC OpenMP::OpenMP_CXX)
endif()

if(USE_AVX2)
    target_compile_options(myapp PRIVATE -mavx2)
endif()

重要注意事项：

1. 作用域
   option() 定义的变量是全局缓存变量，整个项目可见。
2. 默认值覆盖
   若需强制更新默认值（即使缓存存在），需先清除缓存：

   unset(<variable_name> CACHE)  # 清除旧缓存
   option(<variable_name> ...)    # 重新声明
   

3. GUI 显示
   在 cmake-gui 中，选项会显示为复选框，描述文本为 <help_text>：

   [ ] ENABLE_DEBUG   Enable debug mode
   

完整项目示例

目录结构：

project/
├── CMakeLists.txt
├── main.cpp
└── tests/
    └── CMakeLists.txt

project/CMakeLists.txt:

cmake_minimum_required(VERSION 3.10)
project(OptionDemo)

# 定义选项
option(BUILD_TESTS "Build test suite" ON)
option(ENABLE_LOGGING "Enable logging" OFF)

# 主目标
add_executable(main_app main.cpp)

# 条件编译选项
if(ENABLE_LOGGING)
    target_compile_definitions(main_app PRIVATE ENABLE_LOGGING)
endif()

# 条件包含子目录
if(BUILD_TESTS)
    message(STATUS "Including tests")
    add_subdirectory(tests)
endif()

配置与构建：

# 启用日志，禁用测试
cmake -B build -DENABLE_LOGGING=ON -DBUILD_TESTS=OFF
cmake --build build