| .. cmake-manual-description: CMake Policies Reference |
| |
| cmake-policies(7) |
| ***************** |
| |
| .. only:: html |
| |
| .. contents:: |
| |
| Introduction |
| ============ |
| |
| Policies in CMake are used to preserve backward compatible behavior |
| across multiple releases. When a new policy is introduced, newer CMake |
| versions will begin to warn about the backward compatible behavior. It |
| is possible to disable the warning by explicitly requesting the OLD, or |
| backward compatible behavior using the :command:`cmake_policy` command. |
| It is also possible to request ``NEW``, or non-backward compatible behavior |
| for a policy, also avoiding the warning. Each policy can also be set to |
| either ``NEW`` or ``OLD`` behavior explicitly on the command line with the |
| :variable:`CMAKE_POLICY_DEFAULT_CMP<NNNN>` variable. |
| |
| Note that policies are not reliable feature toggles. A policy should |
| almost never be set to ``OLD``, except to silence warnings in an otherwise |
| frozen or stable codebase, or temporarily as part of a larger migration |
| path. The ``OLD`` behavior of each policy is undesirable and will be |
| replaced with an error condition in a future release. |
| |
| The :command:`cmake_minimum_required` command does more than report an |
| error if a too-old version of CMake is used to build a project. It |
| also sets all policies introduced in that CMake version or earlier to |
| ``NEW`` behavior. To manage policies without increasing the minimum required |
| CMake version, the :command:`if(POLICY)` command may be used: |
| |
| .. code-block:: cmake |
| |
| if(POLICY CMP0990) |
| cmake_policy(SET CMP0990 NEW) |
| endif() |
| |
| This has the effect of using the ``NEW`` behavior with newer CMake releases which |
| users may be using and not issuing a compatibility warning. |
| |
| The setting of a policy is confined in some cases to not propagate to the |
| parent scope. For example, if the files read by the :command:`include` command |
| or the :command:`find_package` command contain a use of :command:`cmake_policy`, |
| that policy setting will not affect the caller by default. Both commands accept |
| an optional ``NO_POLICY_SCOPE`` keyword to control this behavior. |
| |
| The :variable:`CMAKE_MINIMUM_REQUIRED_VERSION` variable may also be used |
| to determine whether to report an error on use of deprecated macros or |
| functions. |
| |
| All Policies |
| ============ |
| |
| .. toctree:: |
| :maxdepth: 1 |
| |
| /policy/CMP0000 |
| /policy/CMP0001 |
| /policy/CMP0002 |
| /policy/CMP0003 |
| /policy/CMP0004 |
| /policy/CMP0005 |
| /policy/CMP0006 |
| /policy/CMP0007 |
| /policy/CMP0008 |
| /policy/CMP0009 |
| /policy/CMP0010 |
| /policy/CMP0011 |
| /policy/CMP0012 |
| /policy/CMP0013 |
| /policy/CMP0014 |
| /policy/CMP0015 |
| /policy/CMP0016 |
| /policy/CMP0017 |
| /policy/CMP0018 |
| /policy/CMP0019 |
| /policy/CMP0020 |
| /policy/CMP0021 |
| /policy/CMP0022 |
| /policy/CMP0023 |
| /policy/CMP0024 |
| /policy/CMP0025 |
| /policy/CMP0026 |
| /policy/CMP0027 |
| /policy/CMP0028 |
| /policy/CMP0029 |
| /policy/CMP0030 |
| /policy/CMP0031 |
| /policy/CMP0032 |
| /policy/CMP0033 |
| /policy/CMP0034 |
| /policy/CMP0035 |
| /policy/CMP0036 |
| /policy/CMP0037 |
| /policy/CMP0038 |
| /policy/CMP0039 |
| /policy/CMP0040 |
| /policy/CMP0041 |
| /policy/CMP0042 |
| /policy/CMP0043 |
| /policy/CMP0044 |
| /policy/CMP0045 |
| /policy/CMP0046 |
| /policy/CMP0047 |
| /policy/CMP0048 |
| /policy/CMP0049 |
| /policy/CMP0050 |
| /policy/CMP0051 |
| /policy/CMP0052 |
| /policy/CMP0053 |
| /policy/CMP0054 |
| /policy/CMP0055 |
| /policy/CMP0056 |