Help/manual/cmake-policies.7.rst

   1 .. cmake-manual-description: CMake Policies Reference
   2
   3 cmake-policies(7)
   4 *****************
   5
   6 .. only:: html
   7
   8    .. contents::
   9
  10 Introduction
  11 ============
  12
  13 Policies in CMake are used to preserve backward compatible behavior
  14 across multiple releases.  When a new policy is introduced, newer CMake
  15 versions will begin to warn about the backward compatible behavior.  It
  16 is possible to disable the warning by explicitly requesting the OLD, or
  17 backward compatible behavior using the :command:`cmake_policy` command.
  18 It is also possible to request ``NEW``, or non-backward compatible behavior
  19 for a policy, also avoiding the warning.  Each policy can also be set to
  20 either ``NEW`` or ``OLD`` behavior explicitly on the command line with the
  21 :variable:`CMAKE_POLICY_DEFAULT_CMP<NNNN>` variable.
  22
  23 A policy is a deprecation mechanism and not a reliable feature toggle.
  24 A policy should almost never be set to ``OLD``, except to silence warnings
  25 in an otherwise frozen or stable codebase, or temporarily as part of a
  26 larger migration path. The ``OLD`` behavior of each policy is undesirable
  27 and will be replaced with an error condition in a future release.
  28
  29 The :command:`cmake_minimum_required` command does more than report an
  30 error if a too-old version of CMake is used to build a project.  It
  31 also sets all policies introduced in that CMake version or earlier to
  32 ``NEW`` behavior.  To manage policies without increasing the minimum required
  33 CMake version, the :command:`if(POLICY)` command may be used:
  34
  35 .. code-block:: cmake
  36
  37   if(POLICY CMP0990)
  38     cmake_policy(SET CMP0990 NEW)
  39   endif()
  40
  41 This has the effect of using the ``NEW`` behavior with newer CMake releases which
  42 users may be using and not issuing a compatibility warning.
  43
  44 The setting of a policy is confined in some cases to not propagate to the
  45 parent scope.  For example, if the files read by the :command:`include` command
  46 or the :command:`find_package` command contain a use of :command:`cmake_policy`,
  47 that policy setting will not affect the caller by default.  Both commands accept
  48 an optional ``NO_POLICY_SCOPE`` keyword to control this behavior.
  49
  50 The :variable:`CMAKE_MINIMUM_REQUIRED_VERSION` variable may also be used
  51 to determine whether to report an error on use of deprecated macros or
  52 functions.
  53
  54
  55 Policies Introduced by CMake 3.24
  56 =================================
  57
  58 .. toctree::
  59    :maxdepth: 1
  60
  61    CMP0139: The if() command supports path comparisons using PATH_EQUAL operator. </policy/CMP0139>
  62    CMP0138: CheckIPOSupported uses flags from calling project. </policy/CMP0138>
  63    CMP0137: try_compile() passes platform variables in project mode. </policy/CMP0137>
  64    CMP0136: Watcom runtime library flags are selected by an abstraction. </policy/CMP0136>
  65    CMP0135: ExternalProject ignores timestamps in archives by default for the URL download method. </policy/CMP0135>
  66    CMP0134: Fallback to "HOST" Windows registry view when "TARGET" view is not usable. </policy/CMP0134>
  67    CMP0133: The CPack module disables SLA by default in the CPack DragNDrop Generator. </policy/CMP0133>
  68    CMP0132: Do not set compiler environment variables on first run. </policy/CMP0132>
  69    CMP0131: LINK_LIBRARIES supports the LINK_ONLY generator expression. </policy/CMP0131>
  70    CMP0130: while() diagnoses condition evaluation errors. </policy/CMP0130>
  71
  72 Policies Introduced by CMake 3.23
  73 =================================
  74
  75 .. toctree::
  76    :maxdepth: 1
  77
  78    CMP0129: Compiler id for MCST LCC compilers is now LCC, not GNU. </policy/CMP0129>
  79
  80 Policies Introduced by CMake 3.22
  81 =================================
  82
  83 .. toctree::
  84    :maxdepth: 1
  85
  86    CMP0128: Selection of language standard and extension flags improved. </policy/CMP0128>
  87    CMP0127: cmake_dependent_option() supports full Condition Syntax. </policy/CMP0127>
  88
  89 Policies Introduced by CMake 3.21
  90 =================================
  91
  92 .. toctree::
  93    :maxdepth: 1
  94
  95    CMP0126: set(CACHE) does not remove a normal variable of the same name. </policy/CMP0126>
  96    CMP0125: find_(path|file|library|program) have consistent behavior for cache variables. </policy/CMP0125>
  97    CMP0124: foreach() loop variables are only available in the loop scope. </policy/CMP0124>
  98    CMP0123: ARMClang cpu/arch compile and link flags must be set explicitly. </policy/CMP0123>
  99    CMP0122: UseSWIG use standard library name conventions for csharp language. </policy/CMP0122>
 100    CMP0121: The list command detects invalid indices. </policy/CMP0121>
 101
 102 Policies Introduced by CMake 3.20
 103 =================================
 104
 105 .. toctree::
 106    :maxdepth: 1
 107
 108    CMP0120: The WriteCompilerDetectionHeader module is removed. </policy/CMP0120>
 109    CMP0119: LANGUAGE source file property explicitly compiles as language. </policy/CMP0119>
 110    CMP0118: The GENERATED source file property is now visible in all directories. </policy/CMP0118>
 111    CMP0117: MSVC RTTI flag /GR is not added to CMAKE_CXX_FLAGS by default. </policy/CMP0117>
 112    CMP0116: Ninja generators transform DEPFILEs from add_custom_command(). </policy/CMP0116>
 113    CMP0115: Source file extensions must be explicit. </policy/CMP0115>
 114
 115 Policies Introduced by CMake 3.19
 116 =================================
 117
 118 .. toctree::
 119    :maxdepth: 1
 120
 121    CMP0114: ExternalProject step targets fully adopt their steps. </policy/CMP0114>
 122    CMP0113: Makefile generators do not repeat custom commands from target dependencies. </policy/CMP0113>
 123    CMP0112: Target file component generator expressions do not add target dependencies. </policy/CMP0112>
 124    CMP0111: An imported target missing its location property fails during generation. </policy/CMP0111>
 125    CMP0110: add_test() supports arbitrary characters in test names. </policy/CMP0110>
 126    CMP0109: find_program() requires permission to execute but not to read. </policy/CMP0109>
 127
 128 Policies Introduced by CMake 3.18
 129 =================================
 130
 131 .. toctree::
 132    :maxdepth: 1
 133
 134    CMP0108: A target cannot link to itself through an alias. </policy/CMP0108>
 135    CMP0107: An ALIAS target cannot overwrite another target. </policy/CMP0107>
 136    CMP0106: The Documentation module is removed. </policy/CMP0106>
 137    CMP0105: Device link step uses the link options. </policy/CMP0105>
 138    CMP0104: CMAKE_CUDA_ARCHITECTURES now detected for NVCC, empty CUDA_ARCHITECTURES not allowed. </policy/CMP0104>
 139    CMP0103: Multiple export() with same FILE without APPEND is not allowed. </policy/CMP0103>
 140
 141 Policies Introduced by CMake 3.17
 142 =================================
 143
 144 .. toctree::
 145    :maxdepth: 1
 146
 147    CMP0102: mark_as_advanced() does nothing if a cache entry does not exist. </policy/CMP0102>
 148    CMP0101: target_compile_options honors BEFORE keyword in all scopes. </policy/CMP0101>
 149    CMP0100: Let AUTOMOC and AUTOUIC process .hh header files. </policy/CMP0100>
 150    CMP0099: Link properties are transitive over private dependency on static libraries. </policy/CMP0099>
 151    CMP0098: FindFLEX runs flex in CMAKE_CURRENT_BINARY_DIR when executing. </policy/CMP0098>
 152
 153 Policies Introduced by CMake 3.16
 154 =================================
 155
 156 .. toctree::
 157    :maxdepth: 1
 158
 159    CMP0097: ExternalProject_Add with GIT_SUBMODULES "" initializes no submodules. </policy/CMP0097>
 160    CMP0096: project() preserves leading zeros in version components. </policy/CMP0096>
 161    CMP0095: RPATH entries are properly escaped in the intermediary CMake install script. </policy/CMP0095>
 162
 163 Policies Introduced by CMake 3.15
 164 =================================
 165
 166 .. toctree::
 167    :maxdepth: 1
 168
 169    CMP0094: FindPython3, FindPython2 and FindPython use LOCATION for lookup strategy. </policy/CMP0094>
 170    CMP0093: FindBoost reports Boost_VERSION in x.y.z format. </policy/CMP0093>
 171    CMP0092: MSVC warning flags are not in CMAKE_{C,CXX}_FLAGS by default. </policy/CMP0092>
 172    CMP0091: MSVC runtime library flags are selected by an abstraction. </policy/CMP0091>
 173    CMP0090: export(PACKAGE) does not populate package registry by default. </policy/CMP0090>
 174    CMP0089: Compiler id for IBM Clang-based XL compilers is now XLClang. </policy/CMP0089>
 175
 176 Policies Introduced by CMake 3.14
 177 =================================
 178
 179 .. toctree::
 180    :maxdepth: 1
 181
 182    CMP0088: FindBISON runs bison in CMAKE_CURRENT_BINARY_DIR when executing. </policy/CMP0088>
 183    CMP0087: install(SCRIPT | CODE) supports generator expressions. </policy/CMP0087>
 184    CMP0086: UseSWIG honors SWIG_MODULE_NAME via -module flag. </policy/CMP0086>
 185    CMP0085: IN_LIST generator expression handles empty list items. </policy/CMP0085>
 186    CMP0084: The FindQt module does not exist for find_package(). </policy/CMP0084>
 187    CMP0083: Add PIE options when linking executable. </policy/CMP0083>
 188    CMP0082: Install rules from add_subdirectory() are interleaved with those in caller. </policy/CMP0082>
 189
 190
 191 Policies Introduced by CMake 3.13
 192 =================================
 193
 194 .. toctree::
 195    :maxdepth: 1
 196
 197    CMP0081: Relative paths not allowed in LINK_DIRECTORIES target property. </policy/CMP0081>
 198    CMP0080: BundleUtilities cannot be included at configure time. </policy/CMP0080>
 199    CMP0079: target_link_libraries allows use with targets in other directories. </policy/CMP0079>
 200    CMP0078: UseSWIG generates standard target names. </policy/CMP0078>
 201    CMP0077: option() honors normal variables. </policy/CMP0077>
 202    CMP0076: target_sources() command converts relative paths to absolute. </policy/CMP0076>
 203
 204 Policies Introduced by CMake 3.12
 205 =================================
 206
 207 .. toctree::
 208    :maxdepth: 1
 209
 210    CMP0075: Include file check macros honor CMAKE_REQUIRED_LIBRARIES. </policy/CMP0075>
 211    CMP0074: find_package uses PackageName_ROOT variables. </policy/CMP0074>
 212    CMP0073: Do not produce legacy _LIB_DEPENDS cache entries. </policy/CMP0073>
 213
 214 Policies Introduced by CMake 3.11
 215 =================================
 216
 217 .. toctree::
 218    :maxdepth: 1
 219
 220    CMP0072: FindOpenGL prefers GLVND by default when available. </policy/CMP0072>
 221
 222 Policies Introduced by CMake 3.10
 223 =================================
 224
 225 .. toctree::
 226    :maxdepth: 1
 227
 228    CMP0071: Let AUTOMOC and AUTOUIC process GENERATED files. </policy/CMP0071>
 229    CMP0070: Define file(GENERATE) behavior for relative paths. </policy/CMP0070>
 230
 231 Policies Introduced by CMake 3.9
 232 ================================
 233
 234 .. toctree::
 235    :maxdepth: 1
 236
 237    CMP0069: INTERPROCEDURAL_OPTIMIZATION is enforced when enabled. </policy/CMP0069>
 238    CMP0068: RPATH settings on macOS do not affect install_name. </policy/CMP0068>
 239
 240 Policies Introduced by CMake 3.8
 241 ================================
 242
 243 .. toctree::
 244    :maxdepth: 1
 245
 246    CMP0067: Honor language standard in try_compile() source-file signature. </policy/CMP0067>
 247
 248 Policies Introduced by CMake 3.7
 249 ================================
 250
 251 .. toctree::
 252    :maxdepth: 1
 253
 254    CMP0066: Honor per-config flags in try_compile() source-file signature. </policy/CMP0066>
 255
 256 Policies Introduced by CMake 3.4
 257 ================================
 258
 259 .. toctree::
 260    :maxdepth: 1
 261
 262    CMP0065: Do not add flags to export symbols from executables without the ENABLE_EXPORTS target property. </policy/CMP0065>
 263    CMP0064: Support new TEST if() operator. </policy/CMP0064>
 264
 265 Policies Introduced by CMake 3.3
 266 ================================
 267
 268 .. toctree::
 269    :maxdepth: 1
 270
 271    CMP0063: Honor visibility properties for all target types. </policy/CMP0063>
 272    CMP0062: Disallow install() of export() result. </policy/CMP0062>
 273    CMP0061: CTest does not by default tell make to ignore errors (-i). </policy/CMP0061>
 274    CMP0060: Link libraries by full path even in implicit directories. </policy/CMP0060>
 275    CMP0059: Do not treat DEFINITIONS as a built-in directory property. </policy/CMP0059>
 276    CMP0058: Ninja requires custom command byproducts to be explicit. </policy/CMP0058>
 277    CMP0057: Support new IN_LIST if() operator. </policy/CMP0057>
 278
 279 Policies Introduced by CMake 3.2
 280 ================================
 281
 282 .. toctree::
 283    :maxdepth: 1
 284
 285    CMP0056: Honor link flags in try_compile() source-file signature. </policy/CMP0056>
 286    CMP0055: Strict checking for break() command. </policy/CMP0055>
 287
 288 Policies Introduced by CMake 3.1
 289 ================================
 290
 291 .. toctree::
 292    :maxdepth: 1
 293
 294    CMP0054: Only interpret if() arguments as variables or keywords when unquoted. </policy/CMP0054>
 295    CMP0053: Simplify variable reference and escape sequence evaluation. </policy/CMP0053>
 296    CMP0052: Reject source and build dirs in installed INTERFACE_INCLUDE_DIRECTORIES. </policy/CMP0052>
 297    CMP0051: List TARGET_OBJECTS in SOURCES target property. </policy/CMP0051>
 298
 299 Policies Introduced by CMake 3.0
 300 ================================
 301
 302 .. toctree::
 303    :maxdepth: 1
 304
 305    CMP0050: Disallow add_custom_command SOURCE signatures. </policy/CMP0050>
 306    CMP0049: Do not expand variables in target source entries. </policy/CMP0049>
 307    CMP0048: project() command manages VERSION variables. </policy/CMP0048>
 308    CMP0047: Use QCC compiler id for the qcc drivers on QNX. </policy/CMP0047>
 309    CMP0046: Error on non-existent dependency in add_dependencies. </policy/CMP0046>
 310    CMP0045: Error on non-existent target in get_target_property. </policy/CMP0045>
 311    CMP0044: Case sensitive Lang_COMPILER_ID generator expressions. </policy/CMP0044>
 312    CMP0043: Ignore COMPILE_DEFINITIONS_Config properties. </policy/CMP0043>
 313    CMP0042: MACOSX_RPATH is enabled by default. </policy/CMP0042>
 314    CMP0041: Error on relative include with generator expression. </policy/CMP0041>
 315    CMP0040: The target in the TARGET signature of add_custom_command() must exist. </policy/CMP0040>
 316    CMP0039: Utility targets may not have link dependencies. </policy/CMP0039>
 317    CMP0038: Targets may not link directly to themselves. </policy/CMP0038>
 318    CMP0037: Target names should not be reserved and should match a validity pattern. </policy/CMP0037>
 319    CMP0036: The build_name command should not be called. </policy/CMP0036>
 320    CMP0035: The variable_requires command should not be called. </policy/CMP0035>
 321    CMP0034: The utility_source command should not be called. </policy/CMP0034>
 322    CMP0033: The export_library_dependencies command should not be called. </policy/CMP0033>
 323    CMP0032: The output_required_files command should not be called. </policy/CMP0032>
 324    CMP0031: The load_command command should not be called. </policy/CMP0031>
 325    CMP0030: The use_mangled_mesa command should not be called. </policy/CMP0030>
 326    CMP0029: The subdir_depends command should not be called. </policy/CMP0029>
 327    CMP0028: Double colon in target name means ALIAS or IMPORTED target. </policy/CMP0028>
 328    CMP0027: Conditionally linked imported targets with missing include directories. </policy/CMP0027>
 329    CMP0026: Disallow use of the LOCATION target property. </policy/CMP0026>
 330    CMP0025: Compiler id for Apple Clang is now AppleClang. </policy/CMP0025>
 331    CMP0024: Disallow include export result. </policy/CMP0024>
 332
 333 Policies Introduced by CMake 2.8
 334 ================================
 335
 336 .. toctree::
 337    :maxdepth: 1
 338
 339    CMP0023: Plain and keyword target_link_libraries signatures cannot be mixed. </policy/CMP0023>
 340    CMP0022: INTERFACE_LINK_LIBRARIES defines the link interface. </policy/CMP0022>
 341    CMP0021: Fatal error on relative paths in INCLUDE_DIRECTORIES target property. </policy/CMP0021>
 342    CMP0020: Automatically link Qt executables to qtmain target on Windows. </policy/CMP0020>
 343    CMP0019: Do not re-expand variables in include and link information. </policy/CMP0019>
 344    CMP0018: Ignore CMAKE_SHARED_LIBRARY_Lang_FLAGS variable. </policy/CMP0018>
 345    CMP0017: Prefer files from the CMake module directory when including from there. </policy/CMP0017>
 346    CMP0016: target_link_libraries() reports error if its only argument is not a target. </policy/CMP0016>
 347    CMP0015: link_directories() treats paths relative to the source dir. </policy/CMP0015>
 348    CMP0014: Input directories must have CMakeLists.txt. </policy/CMP0014>
 349    CMP0013: Duplicate binary directories are not allowed. </policy/CMP0013>
 350    CMP0012: if() recognizes numbers and boolean constants. </policy/CMP0012>
 351
 352 Policies Introduced by CMake 2.6
 353 ================================
 354
 355 .. toctree::
 356    :maxdepth: 1
 357
 358    CMP0011: Included scripts do automatic cmake_policy PUSH and POP. </policy/CMP0011>
 359    CMP0010: Bad variable reference syntax is an error. </policy/CMP0010>
 360    CMP0009: FILE GLOB_RECURSE calls should not follow symlinks by default. </policy/CMP0009>
 361    CMP0008: Libraries linked by full-path must have a valid library file name. </policy/CMP0008>
 362    CMP0007: list command no longer ignores empty elements. </policy/CMP0007>
 363    CMP0006: Installing MACOSX_BUNDLE targets requires a BUNDLE DESTINATION. </policy/CMP0006>
 364    CMP0005: Preprocessor definition values are now escaped automatically. </policy/CMP0005>
 365    CMP0004: Libraries linked may not have leading or trailing whitespace. </policy/CMP0004>
 366    CMP0003: Libraries linked via full path no longer produce linker search paths. </policy/CMP0003>
 367    CMP0002: Logical target names must be globally unique. </policy/CMP0002>
 368    CMP0001: CMAKE_BACKWARDS_COMPATIBILITY should no longer be used. </policy/CMP0001>
 369    CMP0000: A minimum required CMake version must be specified. </policy/CMP0000>