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
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
OLD behavior explicitly on the command line with the
A policy is a deprecation mechanism and not a reliable feature toggle. 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.
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
if(POLICY) command may be used:
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
include() command or the
find_package() command contain a use of
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.
CMAKE_MINIMUM_REQUIRED_VERSION variable may also be used to determine whether to report an error on use of deprecated macros or functions.
© 2000–2020 Kitware, Inc. and Contributors
Licensed under the BSD 3-clause License.