CMake中cmake_minimum_required的使用

Posted 2022-11-26 fengbingchun

      CMake中的命令cmake_minimum_required用于设定需要的最低版本的CMake。其格式如下：

cmake_minimum_required(VERSION <min>[...<policy_max>] [FATAL_ERROR])

      可选的<policy_max>项在3.12版本中引入。设置project所需的最低cmake版本，还会更新policy设置。<min>和可选的<policy_max>都是major.minor[.patch[.tweak]]形式的CMake版本，而"..."是literal，低版本和高版本之间的连接符号。
      如果CMake运行的版本低于<min>要求的版本，它将停止处理project并报告错误。如果指定可选的<policy_max>版本，它必须至少是<min>版本并影响Policy Settings中所述的policy设置。如果CMake的运行版本低于3.12(older than 3.12)，则额外的"..."点将被视为版本组件分隔符(version component separator)，导致...<policy_max>部分被忽略并保留基于<min>的policy的3.12之前的行为。

# cmake_minimum_required(VERSION 3.24) # CMake Error at test_cmake_minimum_required.cmake:8 (cmake_minimum_required):
#                                      #   CMake 3.24 or higher is required.  You are running version 3.22.1

cmake_minimum_required(VERSION 3.12...3.24) # 由于当前CMake运行版本为3.22,因此...3.24会被忽略

      此命令会将CMAKE_MINIMUM_REQUIRED_VERSION变量的值设置为<min>

cmake_minimum_required(VERSION 3.13)
message("CMAKE_MINIMUM_REQUIRED_VERSION: $CMAKE_MINIMUM_REQUIRED_VERSION") # CMAKE_MINIMUM_REQUIRED_VERSION: 3.13

      FATAL_ERROR选项被CMake 2.6及更高版本接受但被忽略(accepted but ignored)。当CMake版本为2.4或更低版本时应该指定它，此时会fail并触发error，而不仅仅是warning。

cmake_minimum_required(VERSION 3.14 FATAL_ERROR) # FATAL_ERROR被忽略
cmake_minimum_required(VERSION 2.4 FATAL_ERROR) # 指定版本为2.4或更低版本时,好像并不会触发error,仍然是warning,应该是指的当前CMake的运行版本为2.4或更低版本时会触发error
                                                # CMake Deprecation Warning at test_cmake_minimum_required.cmake:17 (cmake_minimum_required):
                                                #   Compatibility with CMake < 2.8.12 will be removed from a future version of CMake.

      注意：
      (1).在调用project命令之前，在顶层(top-level)CMakeLists.txt文件的开头调用cmake_minimum_required命令。在调用可能影响其行为的其它命令之前，建立(establish)版本和policy设置是非常重要的。
      (2).在function内调用cmake_minimum_required会限制调用此function时对function范围的一些影响。例如，CMAKE_MINIMUM_REQUIRED_VERSION变量不会在调用范围内设置。function不会引入自己的policy范围，因此调用者的policy设置会受到影响。通常，不鼓励在function调用cmake_minimum_required。如果在function内调用cmake_minimum_required，那么此命令只在function内起作用。

function(foo)
    cmake_minimum_required(VERSION 3.14) # 在function内调用cmake_minimum_required,则cmake_minimum_required只在此function内起作用
    message("CMAKE_MINIMUM_REQUIRED_VERSION: $CMAKE_MINIMUM_REQUIRED_VERSION") # CMAKE_MINIMUM_REQUIRED_VERSION: 3.14
endfunction()

message("CMAKE_MINIMUM_REQUIRED_VERSION: $CMAKE_MINIMUM_REQUIRED_VERSION") # CMAKE_MINIMUM_REQUIRED_VERSION: 3.22
foo()
message("CMAKE_MINIMUM_REQUIRED_VERSION: $CMAKE_MINIMUM_REQUIRED_VERSION") # CMAKE_MINIMUM_REQUIRED_VERSION: 3.22

      Policy Settings：
      cmake_minimum_required(VERSION)命令隐式调用cmake_policy(VERSION)命令来指定当前project code是为给定的CMake版本范围而写的(is written for the given range of CMake versions)。CMake的运行版本已知的所有policy，并在<min>(或<policy_max>,如果指定)版本或更早版本中引入的所有policy都将设置为使用NEW行为。更高版本中引入的所有policy均未设置(unset)。这有效请求了给定CMake版本的首选行为(behavior preferred)，并告诉较新的CMake版本警告其新policy。
      当指定的<min>版本高于2.4时，该命令会隐式调用：cmake_policy(VERSION <min>[...<max>])，它根据指定的版本范围设置CMake policy。
      当指定的<min>版本为2.4，或更低版本时，该命令会隐式调用：cmake_policy(VERSION 2.4[...<max>])，这为CMake 2.4及更低版本启用兼容功能(compatibility features)。

cmake_minimum_required(VERSION 3.14...3.20)
message("CMAKE_MINIMUM_REQUIRED_VERSION: $CMAKE_MINIMUM_REQUIRED_VERSION") # CMAKE_MINIMUM_REQUIRED_VERSION: 3.14
# cmake_policy(GET CMP0139 var) # 3.24
#                               # CMake Error at test_cmake_minimum_required.cmake:32 (cmake_policy):
#                               #   cmake_policy GET given policy "CMP0139" which is not known to this version of CMake
cmake_policy(GET CMP0081 var) # 3.13
message("var: $var") # var: NEW
cmake_policy(GET CMP0126 var) # 3.21
message("var: $var") # var:
cmake_policy(GET CMP0108 var) # 3.18
message("var: $var") # var: NEW

cmake_minimum_required(VERSION 3.14)
message("CMAKE_MINIMUM_REQUIRED_VERSION: $CMAKE_MINIMUM_REQUIRED_VERSION") # CMAKE_MINIMUM_REQUIRED_VERSION: 3.14
cmake_policy(GET CMP0126 var) # 3.21
message("var: $var") # var:

      执行上述测试代码需要3个文件：build.sh, CMakeLists.txt, test_cmake_minimum_required.cmake

     build.sh内容如下：

#! /bin/bash

# supported input parameters(cmake commands)
params=(function macro cmake_parse_arguments \\
		find_library find_path find_file find_program find_package \\
		cmake_policy cmake_minimum_required project include \\
		string)

usage()

	echo "Error: $0 needs to have an input parameter"

	echo "supported input parameters:"
	for param in $params[@]; do
		echo "  $0 $param"
	done

	exit -1


if [ $# != 1 ]; then
	usage
fi

flag=0
for param in $params[@]; do
	if [ $1 == $param ]; then
		flag=1
		break
	fi
done

if [ $flag == 0 ]; then
	echo "Error: parameter \\"$1\\" is not supported"
	usage
	exit -1
fi

if [[ ! -d "build" ]]; then
	mkdir build
	cd build
else
	cd build
fi

echo "==== test $1 ===="
cmake -DTEST_CMAKE_FEATURE=$1 ..

      CMakeLists.txt内容如下：

cmake_minimum_required(VERSION 3.22)
project(cmake_feature_usage)

message("#### current cmake version: $CMAKE_MAJOR_VERSION.$CMAKE_MINOR_VERSION.$CMAKE_PATCH_VERSION")
include(test_$TEST_CMAKE_FEATURE.cmake)
message("==== test finish ====")

      test_cmake_minimum_required.cmake：为上面的所有示例代码

      执行可能的结果如下图所示：

      GitHub： http://github.com/fengbingchun/Linux_Code_Test