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