CMake语法—选项（option）

CMake语法—选项（option）

1 选项

1.1 定义

1.2 说明

• variable 选项名
• help_text 描述、解释、备注
• value 选项初始化值（除ON而外全为OFF）

2 应用注意事项

2.1 代码结构

• learn_cmake：为根目录

• build：为CMake配置输出目录（在此例中即生成sln解决方案的地方）

• CMakeLists.txt：CMake脚本

• cmake_config.bat：执行CMake配置过程的脚本（双击直接运行）

  	@echo off
  	set currentDir=%~dp0
  	set buildDir=%currentDir%
  	set cmakeOutputDir=%currentDir%\build
  	cmake -S %buildDir% -B %cmakeOutputDir% -G"Visual Studio 16 2019" -T v140 -A x64
  	pause

2.2 注意事项

2.2.1 不初始化或赋为非ON的值，全部视为OFF

1. 示例代码

   	cmake_minimum_required(VERSION 3.18)
   	# 设置工程名称
   	set(PROJECT_NAME KAIZEN)
   	# 设置工程版本号
   	set(PROJECT_VERSION "1.0.0.10" CACHE STRING "默认版本号")
   	# 工程定义
   	project(${PROJECT_NAME}
   	LANGUAGES CXX C
   	VERSION ${PROJECT_VERSION}
   	)
   	# 打印开始日志
   	message(STATUS "\n########## BEGIN_TEST_OPTION")
   	## 示例1：不赋值
   	option(${PROJECT_NAME}_BUILD_TEST "构建测试模块")
   	if (DEFINED ${PROJECT_NAME}_BUILD_TEST)
   	message(STATUS "defined KAIZEN_BUILD_TEST")
   	else()
   	message(STATUS "not defined KAIZEN_BUILD_TEST")
   	endif()
   	if (${PROJECT_NAME}_BUILD_TEST)
   	message(STATUS "KAIZEN_BUILD_TEST is ON")
   	else()
   	message(STATUS "KAIZEN_BUILD_TEST is OFF")
   	endif()
   	message(STATUS "\n")
   	## 示例2：赋值为非ON、非OFF值
   	option(${PROJECT_NAME}_BUILD_EXAMPLE "构建示例模块" AAA)
   	if (DEFINED ${PROJECT_NAME}_BUILD_EXAMPLE)
   	message(STATUS "defined KAIZEN_BUILD_EXAMPLE")
   	else()
   	message(STATUS "not defined KAIZEN_BUILD_EXAMPLE")
   	endif()
   	if (${PROJECT_NAME}_BUILD_EXAMPLE)
   	message(STATUS "KAIZEN_BUILD_EXAMPLE_1 is ON")
   	else()
   	message(STATUS "KAIZEN_BUILD_EXAMPLE_1 is OFF")
   	endif()
   	if (${${PROJECT_NAME}_BUILD_TYPE})
   	message(STATUS "KAIZEN_BUILD_EXAMPLE_2 is ON")
   	else()
   	message(STATUS "KAIZEN_BUILD_EXAMPLE_2 is OFF")
   	endif()
   	message(STATUS "\n")
   	## 示例3：赋值为ON
   	option(${PROJECT_NAME}_BUILD_GUI "构建视图模块" ON)
   	if (DEFINED ${PROJECT_NAME}_BUILD_GUI)
   	message(STATUS "defined KAIZEN_BUILD_GUI")
   	else()
   	message(STATUS "not defined KAIZEN_BUILD_GUI")
   	endif()
   	if (${PROJECT_NAME}_BUILD_GUI)
   	message(STATUS "KAIZEN_BUILD_GUI is ON")
   	else()
   	message(STATUS "KAIZEN_BUILD_GUI is OFF")
   	endif()
   	# 打印结束日志
   	message(STATUS "########## END_TEST_OPTION\n")

2. 运行结果

   	-- Selecting Windows SDK version 10.0.18362.0 to target Windows 10.0.17763.
   	-- The CXX compiler identification is MSVC 19.0.24245.0
   	-- The C compiler identification is MSVC 19.0.24245.0
   	-- Detecting CXX compiler ABI info
   	-- Detecting CXX compiler ABI info - done
   	-- Check for working CXX compiler: C:/Program Files (x86)/Microsoft Visual Studio 14.0/VC/bin/amd64/cl.exe - skipped
   	-- Detecting CXX compile features
   	-- Detecting CXX compile features - done
   	-- Detecting C compiler ABI info
   	-- Detecting C compiler ABI info - done
   	-- Check for working C compiler: C:/Program Files (x86)/Microsoft Visual Studio 14.0/VC/bin/amd64/cl.exe - skipped
   	-- Detecting C compile features
   	-- Detecting C compile features - done
   	--
   	########## BEGIN_TEST_OPTION
   	-- defined KAIZEN_BUILD_TEST
   	-- KAIZEN_BUILD_TEST is OFF
   	--
   	-- defined KAIZEN_BUILD_EXAMPLE
   	-- KAIZEN_BUILD_EXAMPLE_1 is OFF
   	-- KAIZEN_BUILD_EXAMPLE_2 is OFF
   	--
   	-- defined KAIZEN_BUILD_GUI
   	-- KAIZEN_BUILD_GUI is ON
   	-- ########## END_TEST_OPTION
   	-- Configuring done
   	-- Generating done
   	-- Build files have been written to: F:/learn_cmake/build
   	请按任意键继续. . .

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

1. 示例代码

   	cmake_minimum_required(VERSION 3.18)
   	# 设置工程名称
   	set(PROJECT_NAME KAIZEN)
   	# 设置工程版本号
   	set(PROJECT_VERSION "1.0.0.10" CACHE STRING "默认版本号")
   	# 工程定义
   	project(${PROJECT_NAME}
   	LANGUAGES CXX C
   	VERSION ${PROJECT_VERSION}
   	)
   	# 打印开始日志
   	message(STATUS "\n########## BEGIN_TEST_OPTION")
   	## 定义之前是看不到的
   	if (DEFINED ${PROJECT_NAME}_BUILD_TEST)
   	message(STATUS "defined KAIZEN_BUILD_TEST")
   	else()
   	message(STATUS "not defined KAIZEN_BUILD_TEST")
   	endif()
   	## 定义语句
   	option(${PROJECT_NAME}_BUILD_TEST "构建测试模块" ON)
   	## 定义后才可以看到
   	if (DEFINED ${PROJECT_NAME}_BUILD_TEST)
   	message(STATUS "defined KAIZEN_BUILD_TEST")
   	else()
   	message(STATUS "not defined KAIZEN_BUILD_TEST")
   	endif()
   	## 定义后再应用
   	if (${PROJECT_NAME}_BUILD_TEST)
   	message(STATUS "KAIZEN_BUILD_TEST is ON")
   	else()
   	message(STATUS "KAIZEN_BUILD_TEST is OFF")
   	endif()
   	# 打印结束日志
   	message(STATUS "########## END_TEST_OPTION\n")

2. 运行结果

   	-- Selecting Windows SDK version 10.0.18362.0 to target Windows 10.0.17763.
   	-- The CXX compiler identification is MSVC 19.0.24245.0
   	-- The C compiler identification is MSVC 19.0.24245.0
   	-- Detecting CXX compiler ABI info
   	-- Detecting CXX compiler ABI info - done
   	-- Check for working CXX compiler: C:/Program Files (x86)/Microsoft Visual Studio 14.0/VC/bin/amd64/cl.exe - skipped
   	-- Detecting CXX compile features
   	-- Detecting CXX compile features - done
   	-- Detecting C compiler ABI info
   	-- Detecting C compiler ABI info - done
   	-- Check for working C compiler: C:/Program Files (x86)/Microsoft Visual Studio 14.0/VC/bin/amd64/cl.exe - skipped
   	-- Detecting C compile features
   	-- Detecting C compile features - done
   	--
   	########## BEGIN_TEST_OPTION
   	-- not defined KAIZEN_BUILD_TEST
   	-- defined KAIZEN_BUILD_TEST
   	-- KAIZEN_BUILD_TEST is ON
   	-- ########## END_TEST_OPTION
   	-- Configuring done
   	-- Generating done
   	-- Build files have been written to: F:/learn_cmake/build
   	请按任意键继续. . .

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

运行2.2.1中的示例代码，然后可以查看build目录下的CMakeCache.txt文件。如下图：

2.2.4 如果出现同名的变量（普通或缓存变量），则option会被忽略

1. 示例代码

   	cmake_minimum_required(VERSION 3.18)
   	# 设置工程名称
   	set(PROJECT_NAME KAIZEN)
   	# 设置工程版本号
   	set(PROJECT_VERSION "1.0.0.10" CACHE STRING "默认版本号")
   	# 工程定义
   	project(${PROJECT_NAME}
   	LANGUAGES CXX C
   	VERSION ${PROJECT_VERSION}
   	)
   	# 打印开始日志
   	message(STATUS "\n########## BEGIN_TEST_OPTION")
   	## 1.1先定义普通变量
   	set(${PROJECT_NAME}_BUILD_TEST "构建测试模块")
   	if (DEFINED ${PROJECT_NAME}_BUILD_TEST)
   	message(STATUS "defined KAIZEN_BUILD_TEST")
   	else()
   	message(STATUS "not defined KAIZEN_BUILD_TEST")
   	endif()
   	message(STATUS "KAIZEN_BUILD_TEST_1: ${${PROJECT_NAME}_BUILD_TEST}\n")
   	## 1.2再定义同名option选项
   	option(${PROJECT_NAME}_BUILD_TEST "构建测试模块" ON)
   	message(STATUS "KAIZEN_BUILD_TEST_2: ${${PROJECT_NAME}_BUILD_TEST}\n")
   	### 2.1先定义option选项
   	option(${PROJECT_NAME}_BUILD_EXAMPLE "构建示例模块" OFF)
   	if (DEFINED ${PROJECT_NAME}_BUILD_EXAMPLE)
   	message(STATUS "defined KAIZEN_BUILD_EXAMPLE")
   	else()
   	message(STATUS "not defined KAIZEN_BUILD_EXAMPLE")
   	endif()
   	message(STATUS "KAIZEN_BUILD_EXAMPLE_1: ${KAIZEN_BUILD_EXAMPLE}")
   	### 2.2再定义普通同名变量
   	set(${PROJECT_NAME}_BUILD_EXAMPLE "构建示例模块")
   	message(STATUS "KAIZEN_BUILD_EXAMPLE_2: ${KAIZEN_BUILD_EXAMPLE}")
   	# 打印结束日志
   	message(STATUS "########## END_TEST_OPTION\n")

2. 运行结果

   	-- Selecting Windows SDK version 10.0.18362.0 to target Windows 10.0.17763.
   	-- The CXX compiler identification is MSVC 19.0.24245.0
   	-- The C compiler identification is MSVC 19.0.24245.0
   	-- Detecting CXX compiler ABI info
   	-- Detecting CXX compiler ABI info - done
   	-- Check for working CXX compiler: C:/Program Files (x86)/Microsoft Visual Studio 14.0/VC/bin/amd64/cl.exe - skipped
   	-- Detecting CXX compile features
   	-- Detecting CXX compile features - done
   	-- Detecting C compiler ABI info
   	-- Detecting C compiler ABI info - done
   	-- Check for working C compiler: C:/Program Files (x86)/Microsoft Visual Studio 14.0/VC/bin/amd64/cl.exe - skipped
   	-- Detecting C compile features
   	-- Detecting C compile features - done
   	--
   	########## BEGIN_TEST_OPTION
   	-- defined KAIZEN_BUILD_TEST
   	-- KAIZEN_BUILD_TEST_1: 构建测试模块
   	-- KAIZEN_BUILD_TEST_2: 构建测试模块
   	-- defined KAIZEN_BUILD_EXAMPLE
   	-- KAIZEN_BUILD_EXAMPLE_1: OFF
   	-- KAIZEN_BUILD_EXAMPLE_2: 构建示例模块
   	-- ########## END_TEST_OPTION
   	-- Configuring done
   	-- Generating done
   	-- Build files have been written to: F:/learn_cmake/build
   	请按任意键继续. . .

2.2.5 CMake命令中通过-D预设同名变量，则option也会被忽略（其本质与2.2.4相同）

1. 示例代码

   	cmake_minimum_required(VERSION 3.18)
   	# 设置工程名称
   	set(PROJECT_NAME KAIZEN)
   	# 设置工程版本号
   	set(PROJECT_VERSION "1.0.0.10" CACHE STRING "默认版本号")
   	# 工程定义
   	project(${ PROJECT_NAME }
   	LANGUAGES CXX C
   	VERSION ${ PROJECT_VERSION }
   	)
   	# 打印开始日志
   	message(STATUS "\n########## BEGIN_TEST_OPTION")
   	if (DEFINED ${ PROJECT_NAME }_BUILD_EXAMPLE)
   	message(STATUS "defined KAIZEN_BUILD_EXAMPLE")
   	else()
   	message(STATUS "not defined KAIZEN_BUILD_EXAMPLE")
   	endif()
   	## 定义option选项
   	option(${ PROJECT_NAME }_BUILD_EXAMPLE "构建示例模块" OFF)
   	message(STATUS "KAIZEN_BUILD_EXAMPLE: ${KAIZEN_BUILD_EXAMPLE}")
   	# 打印结束日志
   	message(STATUS "########## END_TEST_OPTION\n")

2. cmake_config.bat

   	@echo off
   	set currentDir=%~dp0
   	set buildDir=%currentDir%
   	set cmakeOutputDir=%currentDir%\build
   	cmake -S %buildDir% -B %cmakeOutputDir% -G"Visual Studio 16 2019" -T v140 -A x64 -DKAIZEN_BUILD_EXAMPLE=ON
   	pause

3. 运行结果

   	--Selecting Windows SDK version 10.0.18362.0 to target Windows 10.0.17763.
   	--The CXX compiler identification is MSVC 19.0.24245.0
   	--The C compiler identification is MSVC 19.0.24245.0
   	--Detecting CXX compiler ABI info
   	-- Detecting CXX compiler ABI info - done
   	-- Check for working CXX compiler : C: / Program Files(x86) / Microsoft Visual Studio 14.0 / VC / bin / amd64 / cl.exe - skipped
   	-- Detecting CXX compile features
   	-- Detecting CXX compile features - done
   	-- Detecting C compiler ABI info
   	-- Detecting C compiler ABI info - done
   	-- Check for working C compiler : C: / Program Files(x86) / Microsoft Visual Studio 14.0 / VC / bin / amd64 / cl.exe - skipped
   	-- Detecting C compile features
   	-- Detecting C compile features - done
   	--
   	########## BEGIN_TEST_OPTION
   	-- defined KAIZEN_BUILD_EXAMPLE
   	-- KAIZEN_BUILD_EXAMPLE: ON
   	-- ########## END_TEST_OPTION
   	-- Configuring done
   	-- Generating done
   	-- Build files have been written to : F: / learn_cmake / build
   	请按任意键继续. . .

2.2.6 修改option选项值（建议通过缓存变量方式修改）

1. 示例代码

   	cmake_minimum_required(VERSION 3.18)
   	# 设置工程名称
   	set(PROJECT_NAME KAIZEN)
   	# 设置工程版本号
   	set(PROJECT_VERSION "1.0.0.10" CACHE STRING "默认版本号")
   	# 工程定义
   	project(${ PROJECT_NAME }
   	LANGUAGES CXX C
   	VERSION ${ PROJECT_VERSION }
   	)
   	# 打印开始日志
   	message(STATUS "\n########## BEGIN_TEST_OPTION")
   	if (DEFINED ${ PROJECT_NAME }_BUILD_EXAMPLE)
   	message(STATUS "defined KAIZEN_BUILD_EXAMPLE")
   	else()
   	message(STATUS "not defined KAIZEN_BUILD_EXAMPLE")
   	endif()
   	## 定义option选项
   	option(${ PROJECT_NAME }_BUILD_EXAMPLE "构建示例模块" OFF)
   	message(STATUS "KAIZEN_BUILD_EXAMPLE_1: ${KAIZEN_BUILD_EXAMPLE}")
   	## 方式一：修改option选项值（无效方式，请忽略）
   	option(${ PROJECT_NAME }_BUILD_EXAMPLE "构建示例模块" ON)
   	message(STATUS "KAIZEN_BUILD_EXAMPLE_2: ${KAIZEN_BUILD_EXAMPLE}")
   	## 方式二：通过cache变量方式修改（正确方式，力推荐）
   	set(${ PROJECT_NAME }_BUILD_EXAMPLE ON CACHE BOOL "构建示例模块" FORCE)
   	message(STATUS "KAIZEN_BUILD_EXAMPLE_3: ${KAIZEN_BUILD_EXAMPLE}")
   	# 打印结束日志
   	message(STATUS "########## END_TEST_OPTION\n")

2. 运行结果

   	--Selecting Windows SDK version 10.0.18362.0 to target Windows 10.0.17763.
   	--The CXX compiler identification is MSVC 19.0.24245.0
   	--The C compiler identification is MSVC 19.0.24245.0
   	--Detecting CXX compiler ABI info
   	-- Detecting CXX compiler ABI info - done
   	-- Check for working CXX compiler : C: / Program Files(x86) / Microsoft Visual Studio 14.0 / VC / bin / amd64 / cl.exe - skipped
   	-- Detecting CXX compile features
   	-- Detecting CXX compile features - done
   	-- Detecting C compiler ABI info
   	-- Detecting C compiler ABI info - done
   	-- Check for working C compiler : C: / Program Files(x86) / Microsoft Visual Studio 14.0 / VC / bin / amd64 / cl.exe - skipped
   	-- Detecting C compile features
   	-- Detecting C compile features - done
   	--
   	########## BEGIN_TEST_OPTION
   	-- not defined KAIZEN_BUILD_EXAMPLE
   	-- KAIZEN_BUILD_EXAMPLE_1: OFF
   	-- KAIZEN_BUILD_EXAMPLE_2 : OFF
   	-- KAIZEN_BUILD_EXAMPLE_3 : ON
   	-- ########## END_TEST_OPTION
   	-- Configuring done
   	-- Generating done
   	-- Build files have been written to : F: / learn_cmake / build
   	请按任意键继续. . .

   INI 复制 全屏

   当然，也可以通过定义同名普通变量方式进行修改。

   但是，通过普通变量方式修改后，CMakeCache.txt中的值仍然为旧值。感兴趣可自行验证。

   option选项本质与缓存变量相同，即会存储在CMakeCache.txt中。因此修改其值也推荐使用缓存变量的方式，这样会直接修改CMakeCache.txt中的存储值，更彻底、更本质、更安全。