Cmake命令之cmake_minimum_required介绍

命令格式

cmake_minimum_required(VERSION <min>[...<max>] [FATAL_ERROR])
该命令指明了对cmake的最低(高)版本的要求，...为低版本和高版本之间的连接符号，没有其他含义。
命令解析

cmake版本号说明
cmake的版本号格式为major.minor[.patch[.tweak]]，例如cmake的版本号为3.10.2。
参数详解
- VERSION：指明后面的参数为版本号，这个参数是必须的。
- min：指定cmake要求的最低版本号，如果cmake实际版本号低于min指定的版本号，cmake的执行过程会终止。
- max：指定cmake要求的最高版本号，要求该参数不能小于min。如果cmake是3.12之前的版本，...<max>会被忽略，按照min指定的版本参数运行，相当于cmake_minimum_required(VERSION <min>...3.12)。
- FATAL_ERROR：该参数在cmake的2.6及以后的版本被忽略，在cmake的2.4及以前的版本，需要指明该参数，以便cmake能提示失败而不仅仅是一个警告。

举例说明

1. 假设当前的cmake版本为3.10.2

>cmake --version
cmake version 3.10.2

CMake suite maintained and supported by Kitware (kitware.com/cmake).

示1.1：指定了min，且比当前cmake版本低

# CMakeLists.txt文件
cmake_minimum_required (VERSION 2.8.0)

# 执行结果
>cmake .
-- Configuring done
-- Generating done
-- Build files have been written to:XXXXXX

示例1.2：指定了min，且比当前的cmake版本高

# CMakeLists.txt 文件
cmake_minimum_required (VERSION 3.12.0)

# 执行结果
>cmake .
CMake Error at CMakeLists.txt:1 (cmake_minimum_required):
CMake 3.12.0 or higher is required.  You are running version 3.10.2

-- Configuring incomplete, errors occurred!

示例1.3：指定了min,也指定了max，实际上由于当前环境的cmake版本低于3.12，因此...max是会被忽略的

# CMakeLists.txt 文件
cmake_minimum_required (VERSION 3.10.0...3.12.0)

# 执行结果
>cmake .
-- Configuring done
-- Generating done
-- Build files have been written to:XXXXXX

2. 假设当前的cmake版本为3.18.2

>cmake --version
cmake version 3.18.2

CMake suite maintained and supported by Kitware (kitware.com/cmake).

当只指定min的时候，结果和示例1.1、示例1.2一致。如果同时也指定了max，有如下几种情况：
示2.1：指定了max，且比min版本低

# CMakeLists.txt文件
cmake_minimum_required (VERSION 3.12.2...3.10.2)

# 执行结果，会提示错误
>cmake .
CMake Error at CMakeLists.txt:1 (cmake_minimum_required):
Policy VERSION range "3.12.2...3.10.2" specifies a larger minimum than
maximum.

示2.2：指定了max，高于min且比当前运行的cmake版本高

# CMakeLists.txt文件
cmake_minimum_required (VERSION 3.12.2...3.19.2)

# 执行结果
>cmake .
-- Configuring done
-- Generating done
-- Build files have been written to:XXXXXX

示2.3：指定了max，高于min且比当前运行的cmake版本低

# CMakeLists.txt文件
cmake_minimum_required (VERSION 3.12.2...3.16.2)

# 执行结果
>cmake .
-- Configuring done
-- Generating done
-- Build files have been written to:XXXXXX

可以看到，示例2.2和示例2.3在输出结果上没有什么区别，特别是实际运行的cmake版本比max高时，也是正常的，说明max并不是对当前运行的cmake最高版本的限制。实际上这里影响的是cmake版本的策略机制，这部分内容可以参考更多细节部分。

更多细节
1. cmake_minimum_required命令要求放在顶层的CMakeLists.txt文件的最开始，在其他命令执行前调用，这是因为后续的命令的行为表现可能跟版本有关系。
2. 如果在函数内调用cmake_minimum_required，那么这个命令只在函数内起作用。
3. cmake_minimum_required命令的实质是指定了当前工程支持的cmake版本范围，它暗含对cmake_policy的调用，而cmake_policy指定了cmake版本的策略机制，主要是为了保障在不同的cmake版本间的兼容性。
  - cmake的策略机制是为了保证，即使新cmake版本引入变化（新功能或者功能点变更），当前工程的构建仍然可以被兼容。
  - 每一种新的策略机制（cmake版本更新带来的变化）用形如CMP<NNNN>来标识，其中NNNN是一个整数，每一种的策略机制有NEW和OLD两种行为表现，调用方式为cmake_policy(SET CMP<NNNN> OLD)或cmake_policy(SET CMP<NNNN> NEW)。例如策略CMP0000为“必须指定cmake要求的最低版本”，该策略在2.6版本引入，并且不建议使用OLD行为，后续版本会考虑对该策略移除OLD行为；策略CMP0002为“逻辑目标名称必须全局唯一（逻辑目标名称即被add_executable()、add_library()、add_custom_target()创建的名称)”，该策略在2.6版本引入，并且不建议使用OLD行为，后续版本会考虑对该策略移除OLD行为。
  - 对于当前运行cmake版本已知的所有策略，若是在min（或max：运行的cmake高于max时）以及min之前版本引入的，都会被设置为NEW行为，在min之后版本引入的策略，行为不会被设置，需要显式指定（调用cmake_policy或者CMAKE_POLICY_DEFAULT_CMP<NNNN>）。假设运行的cmake版本为3.18.2，min是3.12.2，max是3.13.2，可以看到max小于当前运行的cmake版本(3.13.2<3.18.2)，因此3.13.2之前的策略的模型行为是NEW（CMP0081 = NEW），而3.13.2之后的策略默认为空（CMP0108 =）：
```
 # CMakeLists.txt文件
 cmake_minimum_required (VERSION 3.12.2...3.16.2)

 cmake_policy (GET CMP0108 cmp_0108)# CMP0108为cmake 3.18引入的
 message (">>> cmp0108 = ${cmp_0108}")

 cmake_policy (GET CMP0081 cmp_0081) # CMP0081为cmake 3.13引入的
 message (">>> cmp0081 = ${cmp_0081}")
```
```
# 执行结果
>cmake .
>>> cmp0108 =
>>> cmp0081 = NEW
```

附录：参考资料

https://cmake.org/cmake/help/latest/command/cmake_minimum_required.html

Cmake命令之cmake_minimum_required介绍

命令格式

命令解析

举例说明

更多细节

附录：参考资料