Cmake命令之cmake_minimum_required介绍

  • 命令格式

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

  • 命令解析

  1. cmake版本号说明
    cmake的版本号格式为major.minor[.patch[.tweak]],例如cmake的版本号为3.10.2。
  2. 参数详解
    • VERSION:指明后面的参数为版本号,这个参数是必须的。
    • min:指定cmake要求的最低版本号,如果cmake实际版本号低于min指定的版本号,cmake的执行过程会终止。
    • max:指定cmake要求的最高版本号,要求该参数不能小于min。如果cmake是3.12之前的版本,...会被忽略,按照min指定的版本参数运行,相当于cmake_minimum_required(VERSION ...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是一个整数,每一种的策略机制有NEWOLD两种行为表现,调用方式为cmake_policy(SET CMP OLD)cmake_policy(SET CMP 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)。假设运行的cmake版本为3.18.2min3.12.2max3.13.2,可以看到max小于当前运行的cmake版本(3.13.2<3.18.2),因此3.13.2之前的策略的模型行为是NEWCMP0081 = 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
      


附录:参考资料

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

你可能感兴趣的:(Cmake命令之cmake_minimum_required介绍)