| Haibo Huang | d00577c | 2020-02-28 16:35:48 -0800 | [diff] [blame] | 1 | cmake_minimum_required |
| 2 | ---------------------- |
| 3 | |
| 4 | Require a minimum version of cmake. |
| 5 | |
| 6 | .. code-block:: cmake |
| 7 | |
| 8 | cmake_minimum_required(VERSION <min>[...<max>] [FATAL_ERROR]) |
| 9 | |
| 10 | Sets the minimum required version of cmake for a project. |
| 11 | Also updates the policy settings as explained below. |
| 12 | |
| 13 | ``<min>`` and the optional ``<max>`` are each CMake versions of the form |
| 14 | ``major.minor[.patch[.tweak]]``, and the ``...`` is literal. |
| 15 | |
| 16 | If the running version of CMake is lower than the ``<min>`` required |
| 17 | version it will stop processing the project and report an error. |
| 18 | The optional ``<max>`` version, if specified, must be at least the |
| 19 | ``<min>`` version and affects policy settings as described below. |
| 20 | If the running version of CMake is older than 3.12, the extra ``...`` |
| 21 | dots will be seen as version component separators, resulting in the |
| 22 | ``...<max>`` part being ignored and preserving the pre-3.12 behavior |
| 23 | of basing policies on ``<min>``. |
| 24 | |
| 25 | The ``FATAL_ERROR`` option is accepted but ignored by CMake 2.6 and |
| 26 | higher. It should be specified so CMake versions 2.4 and lower fail |
| 27 | with an error instead of just a warning. |
| 28 | |
| 29 | .. note:: |
| 30 | Call the ``cmake_minimum_required()`` command at the beginning of |
| 31 | the top-level ``CMakeLists.txt`` file even before calling the |
| 32 | :command:`project` command. It is important to establish version |
| 33 | and policy settings before invoking other commands whose behavior |
| 34 | they may affect. See also policy :policy:`CMP0000`. |
| 35 | |
| 36 | Calling ``cmake_minimum_required()`` inside a :command:`function` |
| 37 | limits some effects to the function scope when invoked. Such calls |
| 38 | should not be made with the intention of having global effects. |
| 39 | |
| 40 | Policy Settings |
| 41 | ^^^^^^^^^^^^^^^ |
| 42 | |
| 43 | The ``cmake_minimum_required(VERSION)`` command implicitly invokes the |
| 44 | :command:`cmake_policy(VERSION)` command to specify that the current |
| 45 | project code is written for the given range of CMake versions. |
| 46 | All policies known to the running version of CMake and introduced |
| 47 | in the ``<min>`` (or ``<max>``, if specified) version or earlier will |
| 48 | be set to use ``NEW`` behavior. All policies introduced in later |
| 49 | versions will be unset. This effectively requests behavior preferred |
| 50 | as of a given CMake version and tells newer CMake versions to warn |
| 51 | about their new policies. |
| 52 | |
| 53 | When a ``<min>`` version higher than 2.4 is specified the command |
| 54 | implicitly invokes |
| 55 | |
| 56 | .. code-block:: cmake |
| 57 | |
| 58 | cmake_policy(VERSION <min>[...<max>]) |
| 59 | |
| 60 | which sets CMake policies based on the range of versions specified. |
| 61 | When a ``<min>`` version 2.4 or lower is given the command implicitly |
| 62 | invokes |
| 63 | |
| 64 | .. code-block:: cmake |
| 65 | |
| 66 | cmake_policy(VERSION 2.4[...<max>]) |
| 67 | |
| 68 | which enables compatibility features for CMake 2.4 and lower. |