1.5 向用户显示选项

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 ，现在为其设置一个默认值，同时也可以从外部进行更改：

1. 用一个选项替换上一个示例的 set(USE_LIBRARY OFF) 命令。该选项将修改 USE_LIBRARY 的值，并设置其默认值为 OFF ：

   option(USE_LIBRARY "Compile sources into a library" OFF)

2. 现在，可以通过 CMake 的 -D CLI 选项，将信息传递给 CMake 来切换库的行为：

   $ 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 设置任何类型的变量：逻辑变量、路径等等。

工作原理

option 可接受三个参数：

option(<option_variable> "help string" [initial value])

• <option_variable> 表示该选项的变量的名称。
• "help string" 记录选项的字符串，在 CMake 的终端或图形用户界面中可见。
• [initial value] 选项的默认值，可以是 ON 或 OFF 。

更多信息

有时选项之间会有依赖的情况。示例中，我们提供生成静态库或动态库的选项。但是，如果没有将 USE_LIBRARY 逻辑设置为 ON ，则此选项没有任何意义。CMake 提供 cmake_dependent_option() 命令用来定义依赖于其他选项的选项：

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 将打印刚才讨论的模块的手册页（帮助页面)。