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