NOTE: 这个示例代码可以在 https://github.com/dev-cafe/cmake-cookbook/tree/v1.0/chapter-01/recipe-05 找到,其中有一个C++示例。该配置在CMake 3.5版(或更高版本)测试有效的,并且已经在GNU/Linux、macOS和Windows上进行了测试。
前面的配置中,我们引入了条件句:通过硬编码的方式给定逻辑变量值。不过,这会影响用户修改这些变量。CMake代码没有向读者传达,该值可以从外部进行修改。推荐在CMakeLists.txt
中使用option()
命令,以选项的形式显示逻辑开关,用于外部设置,从而切换构建系统的生成行为。本节的示例将向您展示,如何使用这个命令。
具体实施
看一下前面示例中的静态/动态库示例。与其硬编码USE_LIBRARY
为ON
或OFF
,现在为其设置一个默认值,同时也可以从外部进行更改:
- 用一个选项替换上一个示例的
set(USE_LIBRARY OFF)
命令。该选项将修改USE_LIBRARY
的值,并设置其默认值为OFF
:option(USE_LIBRARY "Compile sources into a library" OFF)
- 现在,可以通过CMake的
-D
CLI选项,将信息传递给CMake来切换库的行为: ```shell $ mkdir -p build $ cd build $ cmake -D USE_LIBRARY=ON ..
— … — Compile sources into a library? ON — …
$ cmake —build .
Scanning dependencies of target message [ 25%] Building CXX object CMakeFiles/message.dir/Message.cpp.o [ 50%] Linking CXX static library libmessage.a [ 50%] Built target message Scanning dependencies of target hello-world [ 75%] Building CXX object CMakeFiles/hello-world.dir/hello-world.cpp.o [100%] Linking CXX executable hello-world [100%] Built target hello-world
`-D`开关用于为CMake设置任何类型的变量:逻辑变量、路径等等。
<a name="b3fbd195"></a>
## 工作原理
`option`可接受三个参数:
`option(<option_variable> "help string" [initial value])`
- `<option_variable>`表示该选项的变量的名称。
- `"help string"`记录选项的字符串,在CMake的终端或图形用户界面中可见。
- `[initial value]`选项的默认值,可以是`ON`或`OFF`。
<a name="a8690392"></a>
## 更多信息
有时选项之间会有依赖的情况。示例中,我们提供生成静态库或动态库的选项。但是,如果没有将`USE_LIBRARY`逻辑设置为`ON`,则此选项没有任何意义。CMake提供`cmake_dependent_option()`命令用来定义依赖于其他选项的选项:
```cmake
include(CMakeDependentOption)
# second option depends on the value of the first
cmake_dependent_option(
MAKE_STATIC_LIBRARY "Compile sources into a static library" OFF
"USE_LIBRARY" ON
)
# third option depends on the value of the first
cmake_dependent_option(
MAKE_SHARED_LIBRARY "Compile sources into a shared library" ON
"USE_LIBRARY" ON
)
如果USE_LIBRARY
为ON
,MAKE_STATIC_LIBRARY
默认值为OFF
,否则MAKE_SHARED_LIBRARY
默认值为ON
。可以这样运行:
$ cmake -D USE_LIBRARY=OFF -D MAKE_SHARED_LIBRARY=ON ..
这仍然不会构建库,因为USE_LIBRARY
仍然为OFF
。
CMake有适当的机制,通过包含模块来扩展其语法和功能,这些模块要么是CMake自带的,要么是定制的。本例中,包含了一个名为CMakeDependentOption
的模块。如果没有include
这个模块,cmake_dependent_option()
命令将不可用。参见 https://cmake.org/cmake/help/latest/module/CMakeDependentOption.html
TIPS:手册中的任何模块都可以以命令行的方式使用cmake --help-module <name-of-module>
。例如,cmake --help-module CMakeDependentOption
将打印刚才讨论的模块的手册页(帮助页面)。