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

CMake指令：option()

ops 2025/8/5 16:31:20

1.简介

2.常用场景

3.命令行修改选项

4.与 set(... CACHE BOOL ...) 的区别

5.示例代码

6.总结

1.简介

在 CMake 中，option() 是一个专门用于定义布尔类型选项的命令，主要用于控制项目的编译行为，比如是否构建测试、是否启用某个功能模块等。它的作用是创建一个可在 CMake 配置阶段进行调整的开关，用户可以通过命令行参数、CMake GUI 或者 ccmake 来修改这些选项的值。

基本语法：

option(<variable> "<help_text>" [initial value])

<variable>：选项的名称，定义后可在 CMake 脚本中通过 ${variable} 来引用。
<help_text>：对选项的描述信息，会在 CMake GUI 或者 ccmake 中显示，用于帮助用户理解该选项的用途。
[initial value]：选项的初始值，可选参数，默认值为 OFF（即 FALSE）, ON（即TRUE）。

在定义语句执行后才有效，在定义之前均视为未定义（除过在CMake命令中通过-D预定义）

已定义option选项会存储在CMakeCache.txt中。等价于缓存变量作用。

如果出现同名的变量（普通或缓存变量），则option会被忽略，或者CMake命令中通过-D预设同名变量，则option也会被忽略。

2.常用场景

1）控制功能模块的构建

option(BUILD_SHARED_LIBS "Build shared libraries instead of static ones" ON)
option(ENABLE_LOGGING "Enable logging feature" OFF)if(ENABLE_LOGGING)target_compile_definitions(myapp PRIVATE ENABLE_LOGGING)
endif()

2）选择性构建测试

option(BUILD_TESTS "Build unit tests" ON)
option(BUILD_EXAMPLES "Build example applications" ON)if(BUILD_TESTS)enable_testing()add_subdirectory(tests)
endif()if(BUILD_EXAMPLES)add_subdirectory(examples)
endif()

3）启用特定平台的功能

option(USE_SYSTEM_LIB "Use system libraries instead of bundled ones" OFF)if(USE_SYSTEM_LIB)find_package(SomeLibrary REQUIRED)target_link_libraries(myapp PRIVATE SomeLibrary::SomeLibrary)
else()add_subdirectory(3rdparty/somelib)target_link_libraries(myapp PRIVATE somelib)
endif()

3.命令行修改选项

方法1：在运行 CMake 配置时，可以通过 -D 参数来覆盖选项的默认值：

# 禁用测试构建
cmake -DBUILD_TESTS=OFF ..# 启用共享库构建
cmake -DBUILD_SHARED_LIBS=ON ..

方法2：通过cache变量方式修改

## 定义option选项
option(${ PROJECT_NAME }_BUILD_EXAMPLE "构建示例模块" OFF)
message(STATUS "KAIZEN_BUILD_EXAMPLE_1: ${KAIZEN_BUILD_EXAMPLE}")#out: KAIZEN_BUILD_EXAMPLE_1: OFF## 方式一：修改option选项值（无效方式，请忽略）
option(${ PROJECT_NAME }_BUILD_EXAMPLE "构建示例模块" ON)
message(STATUS "KAIZEN_BUILD_EXAMPLE_2: ${KAIZEN_BUILD_EXAMPLE}")#out: KAIZEN_BUILD_EXAMPLE_2: OFF## 方式二：通过cache变量方式修改（正确方式，力推荐）
set(${ PROJECT_NAME }_BUILD_EXAMPLE ON CACHE BOOL "构建示例模块" FORCE)
message(STATUS "KAIZEN_BUILD_EXAMPLE_3: ${KAIZEN_BUILD_EXAMPLE}")#out: KAIZEN_BUILD_EXAMPLE_3 : ON

option()定义的变量本质上是缓存变量（CACHE变量）。当首次定义option()时，若缓存中不存在该变量，则创建并设置默认值；若已存在，则保留缓存值。
使用set(... FORCE)会强制更新缓存中的值，无论之前是否存在或如何设置，从而确保变量被强制启用。

4.与 `set(... CACHE BOOL ...)` 的区别

虽然 option() 和 set(... CACHE BOOL ...) 都能创建可在 CMake 缓存中存储的布尔变量，但它们之间存在一些细微差别：

option()：
- 仅在变量未在缓存中定义时才会设置初始值。
- 初始值参数是可选的，若不提供则默认为 OFF。
- 设计目的是专门创建用户可配置的选项。
set(... CACHE BOOL ...)：
- 无论变量是否已在缓存中定义，都会设置其值，除非使用 FORCE 参数。
- 需要显式指定类型（如 BOOL）。
- 更灵活，可用于创建各种类型的缓存变量。

5.示例代码

下面是一个完整的示例，展示了 option() 命令在实际项目中的应用：

cmake_minimum_required(VERSION 3.10)
project(MyProject VERSION 1.0.0)# 定义选项
option(BUILD_SHARED_LIBS "Build shared libraries" ON)
option(BUILD_TESTS "Build unit tests" ON)
option(ENABLE_PROFILING "Enable profiling support" OFF)# 设置 C++ 标准
set(CMAKE_CXX_STANDARD 17)# 根据选项构建库
if(BUILD_SHARED_LIBS)add_library(my_lib SHARED src/lib.cpp)
else()add_library(my_lib STATIC src/lib.cpp)
endif()# 根据选项添加编译定义
if(ENABLE_PROFILING)target_compile_definitions(my_lib PRIVATE ENABLE_PROFILING)target_link_libraries(my_lib PRIVATE profiling_library)
endif()# 根据选项构建测试
if(BUILD_TESTS)enable_testing()add_executable(my_tests tests/test.cpp)target_link_libraries(my_tests PRIVATE my_lib)add_test(NAME MyTests COMMAND my_tests)
endif()

通过使用 option() 命令，你的项目将变得更加灵活，用户可以根据自己的需求轻松调整编译选项。