1CMAKE-POLICIES(7) CMake CMAKE-POLICIES(7)
2
6 cmake-policies - CMake Policies Reference
7
9 Policies in CMake are used to preserve backward compatible behavior
10 across multiple releases. When a new policy is introduced, newer CMake
11 versions will begin to warn about the backward compatible behavior. It
12 is possible to disable the warning by explicitly requesting the OLD, or
13 backward compatible behavior using the cmake_policy() command. It is
14 also possible to request NEW, or non-backward compatible behavior for a
15 policy, also avoiding the warning. Each policy can also be set to ei‐
16 ther NEW or OLD behavior explicitly on the command line with the
17 CMAKE_POLICY_DEFAULT_CMP<NNNN> variable.
18 A policy is a deprecation mechanism and not a reliable feature toggle.
20 A policy should almost never be set to OLD, except to silence warnings
21 in an otherwise frozen or stable codebase, or temporarily as part of a
22 larger migration path. The OLD behavior of each policy is undesirable
23 and will be replaced with an error condition in a future release.
24 The cmake_minimum_required() command does more than report an error if
26 a too-old version of CMake is used to build a project. It also sets
27 all policies introduced in that CMake version or earlier to NEW behav‐
28 ior. To manage policies without increasing the minimum required CMake
29 version, the if(POLICY) command may be used:
30 if(POLICY CMP0990)
32 cmake_policy(SET CMP0990 NEW)
33 endif()
34 This has the effect of using the NEW behavior with newer CMake releases
36 which users may be using and not issuing a compatibility warning.
37 The setting of a policy is confined in some cases to not propagate to
39 the parent scope. For example, if the files read by the include() com‐
40 mand or the find_package() command contain a use of cmake_policy(),
41 that policy setting will not affect the caller by default. Both com‐
42 mands accept an optional NO_POLICY_SCOPE keyword to control this behav‐
43 ior.
44 The CMAKE_MINIMUM_REQUIRED_VERSION variable may also be used to deter‐
46 mine whether to report an error on use of deprecated macros or func‐
47 tions.
48
50 CMP0128
51 New in version 3.22.
52 When this policy is set to NEW:
55 • <LANG>_EXTENSIONS is initialized to CMAKE_<LANG>_EXTENSIONS if set,
57 otherwise falling back to CMAKE_<LANG>_EXTENSIONS_DEFAULT.
58 • Extensions are correctly enabled/disabled if <LANG>_STANDARD is unset
60 or satisfied by the default.
61 • Standard mode-affecting flags aren't added unless necessary to
63 achieve the specified mode.
64 The OLD behavior:
66 • Initializes <LANG>_EXTENSIONS to CMAKE_<LANG>_EXTENSIONS if set, oth‐
68 erwise falling back to ON.
69 • Always adds a flag if <LANG>_STANDARD is set and <LANG>_STANDARD_RE‐
71 QUIRED is OFF.
72 • If <LANG>_STANDARD is unset:
74 • Doesn't disable extensions even if <LANG>_EXTENSIONS is OFF.
76 • Fails to enable extensions if <LANG>_EXTENSIONS is ON except for
78 the IAR compiler.
79 Code may need to be updated for the NEW behavior in the following
81 cases:
82 • If a standard mode flag previously overridden by CMake's and not used
84 during compiler detection now takes effect due to CMake no longer
85 adding one as the default detected is appropriate.
86 Such code should be converted to either:
88 • Use <LANG>_STANDARD and <LANG>_EXTENSIONS instead of manually
90 adding flags.
91 • Or ensure the manually-specified flags are used during compiler de‐
93 tection.
94 • If extensions were disabled without <LANG>_STANDARD being set CMake
96 previously wouldn't actually disable extensions.
97 Such code should be updated to not disable extensions if they are re‐
99 quired.
100 • If extensions were enabled/disabled when <LANG>_STANDARD was satis‐
102 fied by the compiler's default CMake previously wouldn't actually en‐
103 able/disable extensions.
104 Such code should be updated to set the correct extensions mode.
106 If compiler flags affecting the standard mode are used during compiler
108 detection (for example in a toolchain file using
109 CMAKE_<LANG>_FLAGS_INIT) then they will affect the detected default
110 standard and extensions.
111 Unlike many policies, CMake version 3.22.0 does not warn when the pol‐
113 icy is not set and simply uses the OLD behavior. Use the cmake_policy()
114 command to set it to OLD or NEW explicitly. See documentation of the
115 CMAKE_POLICY_WARNING_CMP0128 variable to control the warning.
116 NOTE:
118 The OLD behavior of a policy is deprecated by definition and may be
119 removed in a future version of CMake.
120 CMP0127
122 New in version 3.22.
123 cmake_dependent_option() supports full Condition Syntax.
126 The <depends> parameter accepts a semicolon-separated list of condi‐
128 tions. CMake 3.21 and lower evaluates each condition as if(${condi‐
129 tion}), which does not properly handle conditions with nested paren
130 groups. CMake 3.22 and above instead prefer to evaluate each condition
131 as if(<condition>), where <condition> is re-parsed as if literally
132 written in a call to if(). This allows expressions like:
133 "A AND (B OR C)"
135 but requires expressions like:
137 "FOO MATCHES (UPPER|lower)"
139 to be re-written as:
141 "FOO MATCHES \"(UPPER|lower)\""
143 Policy CMP0127 provides compatibility for projects that have not been
145 updated to expect the new behavior.
146 This policy was introduced in CMake version 3.22. CMake version 3.22.0
148 warns when the policy is not set and uses OLD behavior. Use the
149 cmake_policy() command to set it to OLD or NEW explicitly.
150 NOTE:
152 The OLD behavior of a policy is deprecated by definition and may be
153 removed in a future version of CMake.
154
156 CMP0126
157 New in version 3.21.
158 When this policy is set to NEW, the set(CACHE) command does not remove
161 any normal variable of the same name from the current scope. The OLD
162 behavior removes any normal variable of the same name from the current
163 scope in the following situations:
164 • No cache variable of that name existed previously.
166 • A cache variable of that name existed previously, but it had no type.
168 This can occur when the variable was set on the command line using a
169 form like cmake -DMYVAR=blah instead of cmake -DMYVAR:STRING=blah.
170 Note that the NEW behavior has an important difference to the similar
172 NEW behavior of policy CMP0077. The set(CACHE) command always sets the
173 cache variable if it did not exist previously, regardless of the
174 CMP0126 policy setting. The option() command will not set the cache
175 variable if a non-cache variable of the same name already exists and
176 CMP0077 is set to NEW.
177 Policy CMP0126 was introduced in CMake version 3.21. Use the cmake_pol‐
179 icy() command to set it to OLD or NEW explicitly. Unlike many poli‐
180 cies, CMake version 3.22.0 does not warn when the policy is not set and
181 simply uses OLD behavior. See documentation of the CMAKE_POLICY_WARN‐
182 ING_CMP0126 variable to control the warning.
183 NOTE:
185 The OLD behavior of a policy is deprecated by definition and may be
186 removed in a future version of CMake.
187 CMP0125
189 New in version 3.21.
190 The find_file(), find_path(), find_library() and find_program() com‐
193 mands cache their result in the variable specified by their first argu‐
194 ment. Prior to CMake 3.21, if a cache variable of that name already
195 existed before the call but the cache variable had no type, any
196 non-cache variable of the same name would be discarded and the cache
197 variable was always used (see also CMP0126 for a different but similar
198 behavior). This contradicts the convention that a non-cache variable
199 should take precedence over a cache variable of the same name. Such a
200 situation can arise if a user sets a cache variable on the command line
201 without specifying a type, such as cmake -DMYVAR=blah ... instead of
202 cmake -DMYVAR:FILEPATH=blah.
203 Related to the above, if a cache variable of the specified name already
205 exists and it does have a type, the various find_...() commands would
206 return that value unchanged. In particular, if it contained a relative
207 path, it would not be converted to an absolute path in this situation.
208 When policy CMP0125 is set to OLD or is unset, the behavior is as de‐
210 scribed above. When it is set to NEW, the behavior is as follows:
211 • If a non-cache variable of the specified name exists when the
213 find_...() command is called, its value will be used regardless of
214 whether a cache variable of the same name already exists or not. A
215 cache variable will not be created in this case if no such cache
216 variable existed before. If a cache variable of the specified name
217 did already exist, the cache will be updated to match the non-cache
218 variable.
219 • The various find...() commands will always provide an absolute path
221 in the result variable, except where a relative path provided by a
222 cache or non-cache variable cannot be resolved to an existing path.
223 This policy was introduced in CMake version 3.21. Use the cmake_pol‐
225 icy() command to set it to OLD or NEW explicitly. Unlike many poli‐
226 cies, CMake version 3.22.0 does not warn when the policy is not set and
227 simply uses OLD behavior.
228 NOTE:
230 The OLD behavior of a policy is deprecated by definition and may be
231 removed in a future version of CMake.
232 CMP0124
234 New in version 3.21.
235 When this policy is set to NEW, the scope of loop variables defined by
238 the foreach() command is restricted to the loop only. They will be un‐
239 set at the end of the loop.
240 The OLD behavior for this policy still clears the loop variables at the
242 end of the loop, but does not unset them. This leaves them as defined,
243 but empty.
244 This policy was introduced in CMake version 3.21. Use the cmake_pol‐
246 icy() command to set it to OLD or NEW explicitly. Unlike many poli‐
247 cies, CMake version 3.22.0 does not warn when the policy is not set and
248 simply uses OLD behavior.
249 NOTE:
251 The OLD behavior of a policy is deprecated by definition and may be
252 removed in a future version of CMake.
253 CMP0123
255 New in version 3.21.
256 ARMClang cpu/arch compile and link flags must be set explicitly.
259 CMake 3.20 and lower automatically maps the CMAKE_SYSTEM_PROCESSOR
261 variable and an undocumented CMAKE_SYSTEM_ARCH to compile and link op‐
262 tions for ARMClang. For example, the -mcpu=cortex-m33 flag is added
263 when CMAKE_SYSTEM_PROCESSOR equals cortex-m33. CMake requires projects
264 to set either variable or it raises a fatal error. However, the
265 project may need to additionally specify CPU features using e.g.
266 -mcpu=cortex-m33+nodsp, conflicting with the -mcpu=cortex-m33 added by
267 CMake. This results in either link errors or unusable binaries.
268 CMake 3.21 and above prefer instead to not add any cpu/arch compile and
270 link flags automatically. Instead, projects must specify them explic‐
271 itly. This policy provides compatibility for projects that have not
272 been updated.
273 The OLD behavior of this policy requires projects that use ARMClang to
275 set either CMAKE_SYSTEM_PROCESSOR or CMAKE_SYSTEM_ARCH and it automati‐
276 cally adds a compile option -mcpu= or -march= and a link option --cpu=
277 based on those variables. The NEW behavior does not add compile or
278 link options, and projects are responsible for setting correct options.
279 This policy was introduced in CMake version 3.21. CMake version 3.22.0
281 warns when the policy is not set and uses OLD behavior. Use the
282 cmake_policy() command to set it to OLD or NEW explicitly.
283 NOTE:
285 The OLD behavior of a policy is deprecated by definition and may be
286 removed in a future version of CMake.
287 CMP0122
289 New in version 3.21.
290 UseSWIG use library name conventions for CSharp language.
293 Starting with CMake 3.21, UseSWIG generates now a library using default
295 naming conventions. This policy provides compatibility with projects
296 that expect the legacy behavior.
297 This policy was introduced in CMake version 3.21. CMake version 3.22.0
299 warns when the policy is not set and uses OLD behavior. Use the
300 cmake_policy() command to set it to OLD or NEW explicitly.
301 NOTE:
303 The OLD behavior of a policy is deprecated by definition and may be
304 removed in a future version of CMake.
305 CMP0121
307 New in version 3.21.
308 The list() command now detects invalid indices.
311 Prior to CMake version 3.21, the list() command's GET, INSERT, SUBLIST,
313 and REMOVE_AT subcommands did not detect invalid index arguments.
314 The OLD behavior of this policy is for invalid indices to be treated as
316 their integer value (if any) at the start of the string. For example,
317 2good4you is a 2 and not_an_integer is a 0. The NEW behavior is for in‐
318 valid indices to trigger an error.
319 This policy was introduced in CMake version 3.21. CMake version 3.22.0
321 warns when the policy is not set and uses OLD behavior. Use the
322 cmake_policy() command to set it to OLD or NEW explicitly.
323 NOTE:
325 The OLD behavior of a policy is deprecated by definition and may be
326 removed in a future version of CMake.
327
329 CMP0120
330 New in version 3.20.
331 The WriteCompilerDetectionHeader module is removed.
334 CMake versions 3.1 through 3.19 provide this module to generate a C++
336 compatibility layer by re-using information from CMake's table of pre‐
337 processor checks for cmake-compile-features(7). However:
338 • Those granular features have been superseded by meta-features for Re‐
340 quiring Language Standards such as cxx_std_11. Therefore no new
341 granular feature checks will be added and projects will need to use
342 other means to conditionally use new C++ features.
343 • The module exposes some of CMake's implementation details directly to
345 C++ translation units.
346 • The module's approach effectively provides a header file with CMake,
348 thus tying the version of the header to the version of CMake. Many
349 projects found that the WriteCompilerDetectionHeader was best used by
350 manually generating its header locally with a recent version of CMake
351 and then bundling it with the project source so that it could be used
352 with older CMake versions.
353 For reasons including the above, CMake 3.20 and above prefer to not
355 provide the WriteCompilerDetectionHeader module. This policy provides
356 compatibility for projects that have not been ported away from it.
357 Projects using the module should be updated to stop using it. Alterna‐
358 tives include:
359 • Bundle a copy of the generated header in the project's source.
361 • Use a third-party alternative, such as the CC0-licensed Hedley.
363 • Drop support for compilers too old to provide the features natively.
365 The OLD behavior of this policy is for inclusion of the deprecated
367 WriteCompilerDetectionHeader module to work. The NEW behavior is for
368 inclusion of the module to fail as if it does not exist.
369 This policy was introduced in CMake version 3.20. CMake version 3.22.0
371 warns when the policy is not set and uses OLD behavior. Use the
372 cmake_policy() command to set it to OLD or NEW explicitly.
373 NOTE:
375 The OLD behavior of a policy is deprecated by definition and may be
376 removed in a future version of CMake.
377 CMP0119
379 New in version 3.20.
380 LANGUAGE source file property explicitly compiles as specified lan‐
383 guage.
384 The LANGUAGE source file property is documented to mean that the source
386 file is written in the specified language. In CMake 3.19 and below,
387 setting this property causes CMake to compile the source file using the
388 compiler for the specified language. However, it only passes an ex‐
389 plicit flag to tell the compiler to treat the source as the specified
390 language for MSVC-like, XL, and Embarcadero compilers for the CXX lan‐
391 guage. CMake 3.20 and above prefer to also explicitly tell the com‐
392 piler to use the specified language using a flag such as -x c on all
393 compilers for which such flags are known.
394 This policy provides compatibility for projects that have not been up‐
396 dated to expect this behavior. For example, some projects were setting
397 the LANGUAGE property to C on assembly-language .S source files in or‐
398 der to compile them using the C compiler. Such projects should be up‐
399 dated to use enable_language(ASM), for which CMake will often choose
400 the C compiler as the assembler on relevant platforms anyway.
401 The OLD behavior for this policy is to interpret the LANGUAGE <LANG>
403 property using its undocumented meaning to "use the <LANG> compiler".
404 The NEW behavior for this policy is to interpret the LANGUAGE <LANG>
405 property using its documented meaning to "compile as a <LANG> source".
406 This policy was introduced in CMake version 3.20. Use the cmake_pol‐
408 icy() command to set it to OLD or NEW explicitly. Unlike many poli‐
409 cies, CMake version 3.22.0 does not warn when this policy is not set
410 and simply uses OLD behavior.
411 NOTE:
413 The OLD behavior of a policy is deprecated by definition and may be
414 removed in a future version of CMake.
415 CMP0118
417 New in version 3.20.
418 The GENERATED source file property is now visible in all directories.
421 Whether or not a source file is generated is an all-or-nothing global
423 property of the source. Consequently, the associated GENERATED prop‐
424 erty is now visible from any directory scope, not only from the scope
425 for which it was set.
426 Additionally, the GENERATED property may now be set only to boolean
428 values, and may not be turned off once turned on.
429 The OLD behavior of this policy is to only allow GENERATED to be visi‐
431 ble from the directory scope for which it was set. The NEW behavior on
432 the other hand allows it to be visible from any scope.
433 This policy was introduced in CMake version 3.20. Use the cmake_pol‐
435 icy() command to set it to OLD or NEW explicitly. Unlike many poli‐
436 cies, CMake version 3.22.0 does not warn when this policy is not set
437 and simply uses OLD behavior with regard to visibility of the GENERATED
438 property. However, CMake does warn about setting the GENERATED prop‐
439 erty to a non-boolean value.
440 CMP0117
442 New in version 3.20.
443 MSVC RTTI flag /GR is not added to CMAKE_CXX_FLAGS by default.
446 When using MSVC-like compilers in CMake 3.19 and below, the RTTI flag
448 /GR is added to CMAKE_CXX_FLAGS by default. This behavior is left from
449 support for MSVC versions from Visual Studio 2003 and below that did
450 not enable RTTI by default. It is no longer necessary. Furthermore,
451 it is problematic for projects that want to change to /GR- programmati‐
452 cally. In particular, it requires string editing of the
453 CMAKE_CXX_FLAGS variable with knowledge of the CMake builtin default so
454 it can be replaced.
455 CMake 3.20 and above prefer to leave out /GR from the value of
457 CMAKE_CXX_FLAGS by default.
458 This policy provides compatibility with projects that have not been up‐
460 dated to expect the lack of the /GR flag. The policy setting takes ef‐
461 fect as of the first project() or enable_language() command that ini‐
462 tializes CMAKE_CXX_FLAGS.
463 NOTE:
465 Once the policy has taken effect at the top of a project for a given
466 language, that choice must be used throughout the tree for that lan‐
467 guage. In projects that have nested projects in subdirectories, be
468 sure to convert everything together.
469 The OLD behavior for this policy is to place the MSVC /GR flag in the
471 default CMAKE_CXX_FLAGS cache entry. The NEW behavior for this policy
472 is to not place the MSVC /GR flag in the default cache entry.
473 This policy was introduced in CMake version 3.20. Use the cmake_pol‐
475 icy() command to set it to OLD or NEW explicitly. Unlike many poli‐
476 cies, CMake version 3.22.0 does not warn when this policy is not set
477 and simply uses OLD behavior.
478 NOTE:
480 The OLD behavior of a policy is deprecated by definition and may be
481 removed in a future version of CMake.
482 CMP0116
484 New in version 3.20.
485 Ninja generators transform DEPFILE s from add_custom_command().
488 In CMake 3.19 and below, files given to the DEPFILE argument of
490 add_custom_command() were passed directly to Ninja's depfile variable
491 without any path resolution. This meant that if add_custom_command()
492 was called from a subdirectory (created by add_subdirectory()), the
493 DEPFILE argument would have to be either an absolute path or a path
494 relative to CMAKE_BINARY_DIR, rather than CMAKE_CURRENT_BINARY_DIR. In
495 addition, no transformation was done on the file listed in DEPFILE,
496 which meant that the paths within the DEPFILE had the same restric‐
497 tions.
498 Starting with CMake 3.20, the DEPFILE argument is relative to
500 CMAKE_CURRENT_BINARY_DIR (unless it is absolute), and the paths in the
501 DEPFILE are also relative to CMAKE_CURRENT_BINARY_DIR. CMake automati‐
502 cally transforms the paths in the DEPFILE (unless they are absolute)
503 after the custom command is run. The file listed in DEPFILE is not mod‐
504 ified in any way. Instead, CMake writes the transformation to its own
505 internal file, and passes this internal file to Ninja's depfile vari‐
506 able. This transformation happens regardless of whether or not DEPFILE
507 is relative, and regardless of whether or not add_custom_command() is
508 called from a subdirectory.
509 The OLD behavior for this policy is to pass the DEPFILE to Ninja unal‐
511 tered. The NEW behavior for this policy is to transform the DEPFILE af‐
512 ter running the custom command. The status of CMP0116 is recorded at
513 the time of the custom command's creation, and you can have custom com‐
514 mands in the same directory with different values for CMP0116 by set‐
515 ting the policy before each custom command.
516 This policy was introduced in CMake version 3.20. Unlike most poli‐
518 cies, CMake version 3.22.0 does not warn by default when this policy is
519 not set (unless DEPFILE is used in a subdirectory) and simply uses OLD
520 behavior. See documentation of the CMAKE_POLICY_WARNING_CMP0116 vari‐
521 able to control the warning.
522 CMP0115
524 New in version 3.20.
525 Source file extensions must be explicit.
528 In CMake 3.19 and below, if a source file could not be found by the
530 name specified, it would append a list of known extensions to the name
531 to see if the file with the extension could be found. For example, this
532 would allow the user to run:
533 add_executable(exe main)
535 and put main.c in the executable without specifying the extension.
537 Starting in CMake 3.20, CMake prefers all source files to have their
539 extensions explicitly listed:
540 add_executable(exe main.c)
542 The OLD behavior for this policy is to implicitly append known exten‐
544 sions to source files if they can't be found. The NEW behavior of this
545 policy is to not append known extensions and require them to be ex‐
546 plicit.
547 This policy was introduced in CMake version 3.20. CMake version 3.22.0
549 warns when the policy is not set and uses OLD behavior. Use the
550 cmake_policy() command to set it to OLD or NEW explicitly.
551 NOTE:
553 The OLD behavior of a policy is deprecated by definition and may be
554 removed in a future version of CMake.
555
557 CMP0114
558 New in version 3.19.
559 ExternalProject step targets fully adopt their steps.
562 The ExternalProject_Add() STEP_TARGETS option, and the ExternalPro‐
564 ject_Add_StepTargets() function, can be used to create build targets
565 for individual steps of an external project.
566 In CMake 3.18 and below, step targets have some limitations:
568 • Step targets always depend on targets named by the ExternalPro‐
570 ject_Add() DEPENDS option even though not all steps need them. In
571 order to allow step targets to be created without those dependencies,
572 the ExternalProject_Add() INDEPENDENT_STEP_TARGETS option or the Ex‐
573 ternalProject_Add_StepTargets() NO_DEPENDS option may be used. How‐
574 ever, adding such "independent" step targets makes sense only for
575 specific steps such as download, update, and patch because they do
576 not need any of the external project's build dependencies. Further‐
577 more, it does not make sense to create independent step targets for
578 steps that depend on non-independent steps. Such rules are not en‐
579 forced, and projects that do not follow them can generate build sys‐
580 tems with confusing and generator-specific behavior.
581 • Step targets hold copies of the custom commands implementing their
583 steps that are separate from the copies in the primary target created
584 by ExternalProject_Add(), and the primary target does not depend on
585 the step targets. In parallel builds that drive the primary target
586 and step targets concurrently, multiple copies of the steps' commands
587 may run concurrently and race each other.
588 Also, prior to policy CMP0113, the step targets generated by Makefile
590 Generators also contain all the custom commands on which their step
591 depends. This can lead to repeated execution of those steps even in
592 serial builds.
593 In CMake 3.19 and above, the ExternalProject module prefers a revised
595 design to address these problems:
596 • Each step is classified as "independent" if it does not depend on
598 other targets named by the ExternalProject_Add() DEPENDS. The prede‐
599 fined steps are automatically classified by default:
600 • The download, update, and patch steps are independent.
602 • The configure, build, test, and install steps are not.
604 For custom steps, the ExternalProject_Add_Step() command provides an
606 INDEPENDENT option to mark them as independent. It is an error to
607 mark a step as independent if it depends on other steps that are not.
608 Note that this use of the term "independent" refers only to indepen‐
609 dence from external targets and is orthogonal to a step's dependen‐
610 cies on other steps.
611 • Step targets created by the ExternalProject_Add() STEP_TARGETS option
613 or the ExternalProject_Add_Step() function are now independent if and
614 only if their steps are marked as independent. The ExternalPro‐
615 ject_Add() INDEPENDENT_STEP_TARGETS option and ExternalPro‐
616 ject_Add_StepTargets() NO_DEPENDS option are no longer allowed.
617 • Step targets, when created, are fully responsible for holding the
619 custom commands implementing their steps. The primary target created
620 by ExternalProject_Add() depends on the step targets, and the step
621 targets depend on each other. The target-level dependencies match
622 the file-level dependencies used by the custom commands for each
623 step.
624 When the ExternalProject_Add() UPDATE_DISCONNECTED or TEST_EX‐
626 CLUDE_FROM_MAIN option is used, or the ExternalProject_Add_Step() EX‐
627 CLUDE_FROM_MAIN option is used for a custom step, some step targets
628 may be created automatically. These are needed to hold the steps
629 commonly depended upon by the primary target and the disconnected
630 step targets.
631 Policy CMP0114 provides compatibility for projects that have not been
633 updated to expect the new behavior. The OLD behavior for this policy
634 is to use the above-documented behavior from 3.18 and below. The NEW
635 behavior for this policy is to use the above-documented behavior pre‐
636 ferred by 3.19 and above.
637 This policy was introduced in CMake version 3.19. CMake version 3.22.0
639 warns when the policy is not set and uses OLD behavior. Use the
640 cmake_policy() command to set it to OLD or NEW explicitly.
641 CMP0113
643 New in version 3.19.
644 Makefile Generators do not repeat custom commands from target dependen‐
647 cies.
648 Consider a chain of custom commands split across two dependent targets:
650 add_custom_command(OUTPUT output-not-created
652 COMMAND ... DEPENDS ...)
653 set_property(SOURCE output-not-created PROPERTY SYMBOLIC 1)
654 add_custom_command(OUTPUT output-created
655 COMMAND ... DEPENDS ${CMAKE_CURRENT_BINARY_DIR}/output-not-created)
656 add_custom_target(first DEPENDS output-not-created)
657 add_custom_target(second DEPENDS output-created)
658 add_dependencies(second first)
659 In CMake 3.18 and lower, the Makefile generators put a copy of both
661 custom commands in the Makefile for target second even though its de‐
662 pendency on target first ensures that the first custom command runs be‐
663 fore the second. Running make second would cause the first custom com‐
664 mand to run once in the first target and then again in the second tar‐
665 get.
666 CMake 3.19 and above prefer to not duplicate custom commands in a tar‐
668 get that are already generated in other targets on which the target de‐
669 pends (directly or indirectly). This policy provides compatibility for
670 projects that have not been updated to expect the new behavior. In
671 particular, projects that relied on the duplicate execution or that did
672 not properly set the SYMBOLIC source file property may be affected.
673 The OLD behavior for this policy is to duplicate custom commands in de‐
675 pendent targets. The NEW behavior of this policy is to not duplicate
676 custom commands in dependent targets.
677 This policy was introduced in CMake version 3.19. Unlike many poli‐
679 cies, CMake version 3.22.0 does not warn when this policy is not set
680 and simply uses OLD behavior.
681 NOTE:
683 The OLD behavior of a policy is deprecated by definition and may be
684 removed in a future version of CMake.
685 CMP0112
687 New in version 3.19.
688 Target file component generator expressions do not add target dependen‐
691 cies.
692 The following target-based generator expressions that query for direc‐
694 tory or file name components no longer add a dependency on the evalu‐
695 ated target.
696 • TARGET_FILE_NAME
698 • TARGET_FILE_DIR
700 • TARGET_LINKER_FILE_BASE_NAME
702 • TARGET_LINKER_FILE_NAME
704 • TARGET_LINKER_FILE_DIR
706 • TARGET_SONAME_FILE_NAME
708 • TARGET_SONAME_FILE_DIR
710 • TARGET_PDB_FILE_NAME
712 • TARGET_PDB_FILE_DIR
714 • TARGET_BUNDLE_DIR
716 • TARGET_BUNDLE_CONTENT_DIR
718 In CMake 3.18 and lower a dependency on the evaluated target of the
720 above generator expressions would always be added. CMake 3.19 and
721 above prefer to not add this dependency. This policy provides compati‐
722 bility for projects that have not been updated to expect the new behav‐
723 ior.
724 The OLD behavior for this policy is to add a dependency on the evalu‐
726 ated target for the above generator expressions. The NEW behavior of
727 this policy is to not add a dependency on the evaluated target for the
728 above generator expressions.
729 This policy was introduced in CMake version 3.19. Unlike many poli‐
731 cies, CMake version 3.22.0 does not warn by default when this policy is
732 not set and simply uses OLD behavior. See documentation of the
733 CMAKE_POLICY_WARNING_CMP0112 variable to control the warning.
734 NOTE:
736 The OLD behavior of a policy is deprecated by definition and may be
737 removed in a future version of CMake.
738 CMP0111
740 New in version 3.19.
741 An imported target missing its location property fails during genera‐
744 tion.
745 Imported Targets for library files and executables require that their
747 location on disk is specified in a target property such as IMPORTED_LO‐
748 CATION, IMPORTED_IMPLIB, or a per-configuration equivalent. If a
749 needed location property is not set, CMake 3.18 and below generate the
750 string <TARGET_NAME>-NOTFOUND in its place, which results in failures
751 of the corresponding rules at build time. CMake 3.19 and above prefer
752 instead to raise an error during generation. This policy provides com‐
753 patibility for projects that have not been updated to expect the new
754 behavior.
755 The OLD behavior of this policy is to generate the location of an im‐
757 ported unknown, static or shared library target as <TARGET_NAME>-NOT‐
758 FOUND if not set. The NEW behavior is to raise an error.
759 This policy was introduced in CMake version 3.19. CMake version 3.22.0
761 warns when the policy is not set and uses OLD behavior. Use the
762 cmake_policy() command to set it to OLD or NEW explicitly.
763 NOTE:
765 The OLD behavior of a policy is deprecated by definition and may be
766 removed in a future version of CMake.
767 CMP0110
769 New in version 3.19.
770 add_test() supports arbitrary characters in test names.
773 add_test() can now (officially) create tests with whitespace and other
775 special characters in its name. Before CMake version 3.19 that was not
776 allowed, however, it was possible to work around this limitation by ex‐
777 plicitly putting escaped quotes around the test's name in the add_test
778 command.
779 Although never officially supported several projects in the wild found
781 and implemented this workaround. However, the new change which offi‐
782 cially allows the add_test command to support whitespace and other spe‐
783 cial characters in test names now breaks that workaround. In order for
784 these projects to work smoothly with newer CMake versions, this policy
785 was introduced.
786 The OLD behavior of this policy is to still prevent add_test from han‐
788 dling whitespace and special characters properly (if not using the men‐
789 tioned workaround). The NEW behavior on the other hand allows names
790 with whitespace and special characters for tests created by add_test.
791 This policy was introduced in CMake version 3.19. CMake version 3.22.0
793 warns when the policy is not set and uses OLD behavior. Use the
794 cmake_policy() command to set it to OLD or NEW explicitly.
795 CMP0109
797 New in version 3.19.
798 find_program() requires permission to execute but not to read.
801 In CMake 3.18 and below, the find_program() command on UNIX would find
803 files that are readable without requiring execute permission, and would
804 not find files that are executable without read permission. In CMake
805 3.19 and above, find_program now prefers to require execute permission
806 but not read permission. This policy provides compatibility with
807 projects that have not been updated to expect the new behavior.
808 The OLD behavior for this policy is for find_program to require read
810 permission but not execute permission. The NEW behavior for this pol‐
811 icy is for find_program to require execute permission but not read per‐
812 mission.
813 This policy was introduced in CMake version 3.19. CMake version 3.22.0
815 warns when the policy is not set and uses OLD behavior. Use the
816 cmake_policy() command to set it to OLD or NEW explicitly.
817 NOTE:
819 The OLD behavior of a policy is deprecated by definition and may be
820 removed in a future version of CMake.
821
823 CMP0108
824 New in version 3.18.
825 A target is not allowed to link to itself even through an ALIAS target.
828 In CMake 3.17 and below, a target can link to a target aliased to it‐
830 self.
831 The OLD behavior for this policy is to allow a target to link to a tar‐
833 get aliased to itself.
834 The NEW behavior of this policy is to prevent a target to link to it‐
836 self through an ALIAS target.
837 This policy was introduced in CMake version 3.17. Use the cmake_pol‐
839 icy() command to set it to OLD or NEW explicitly. Unlike many poli‐
840 cies, CMake version 3.22.0 does not warn when this policy is not set
841 and simply uses OLD behavior.
842 NOTE:
844 The OLD behavior of a policy is deprecated by definition and may be
845 removed in a future version of CMake.
846 CMP0107
848 New in version 3.18.
849 It is not allowed to create an ALIAS target with the same name as an
852 another target.
853 In CMake 3.17 and below, an ALIAS target can overwrite silently an ex‐
855 isting target with the same name.
856 The OLD behavior for this policy is to allow target overwrite.
858 The NEW behavior of this policy is to prevent target overwriting.
860 This policy was introduced in CMake version 3.17. Use the cmake_pol‐
862 icy() command to set it to OLD or NEW explicitly. Unlike many poli‐
863 cies, CMake version 3.22.0 does not warn when this policy is not set
864 and simply uses OLD behavior.
865 NOTE:
867 The OLD behavior of a policy is deprecated by definition and may be
868 removed in a future version of CMake.
869 CMP0106
871 New in version 3.18.
872 The Documentation module is removed.
875 The Documentation was added as a support mechanism for the VTK project
877 and was tuned for that project. Instead of CMake providing this module
878 with (now old) VTK patterns for cache variables and required packages,
879 the module is now deprecated by CMake itself.
880 The OLD behavior of this policy is for Documentation to add cache vari‐
882 ables and find VTK documentation dependent packages. The NEW behavior
883 is to act as an empty module.
884 This policy was introduced in CMake version 3.18. CMake version 3.22.0
886 warns when the policy is not set and uses OLD behavior. Use the
887 cmake_policy() command to set it to OLD or NEW explicitly.
888 NOTE:
890 The OLD behavior of a policy is deprecated by definition and may be
891 removed in a future version of CMake.
892 CMP0105
894 New in version 3.18.
895 LINK_OPTIONS and INTERFACE_LINK_OPTIONS target properties are now used
898 for the device link step.
899 In CMake 3.17 and below, link options are not used by the device link
901 step.
902 The OLD behavior for this policy is to ignore the link options.
904 The NEW behavior of this policy is to use the link options during the
906 device link step.
907 This policy was introduced in CMake version 3.17. Use the cmake_pol‐
909 icy() command to set it to OLD or NEW explicitly. Unlike many poli‐
910 cies, CMake version 3.22.0 does not warn when this policy is not set
911 and simply uses OLD behavior.
912 NOTE:
914 The OLD behavior of a policy is deprecated by definition and may be
915 removed in a future version of CMake.
916 CMP0104
918 New in version 3.18.
919 Initialize CMAKE_CUDA_ARCHITECTURES when CMAKE_CUDA_COMPILER_ID is
922 NVIDIA. Raise an error if CUDA_ARCHITECTURES is empty.
923 CMAKE_CUDA_ARCHITECTURES introduced in CMake 3.18 is used to initialize
925 CUDA_ARCHITECTURES, which passes correct code generation flags to the
926 CUDA compiler.
927 Previous to this users had to manually specify the code generation
929 flags. This policy is for backwards compatibility with manually speci‐
930 fying code generation flags.
931 The OLD behavior for this policy is to not initialize CMAKE_CUDA_ARCHI‐
933 TECTURES when CMAKE_CUDA_COMPILER_ID is NVIDIA. Empty CUDA_ARCHITEC‐
934 TURES is allowed.
935 The NEW behavior of this policy is to initialize CMAKE_CUDA_ARCHITEC‐
937 TURES when CMAKE_CUDA_COMPILER_ID is NVIDIA and raise an error if
938 CUDA_ARCHITECTURES is empty during generation.
939 If CUDA_ARCHITECTURES is set to a false value no architectures flags
941 are passed to the compiler. This is intended to support packagers and
942 the rare cases where full control over the passed flags is required.
943 This policy was introduced in CMake version 3.18. CMake version 3.22.0
945 warns when the policy is not set and uses OLD behavior. Use the
946 cmake_policy() command to set it to OLD or NEW explicitly.
947 NOTE:
949 The OLD behavior of a policy is deprecated by definition and may be
950 removed in a future version of CMake.
951 Examples
953 set_target_properties(tgt PROPERTIES CUDA_ARCHITECTURES "35;50;72")
954 Generates code for real and virtual architectures 30, 50 and 72.
956 set_property(TARGET tgt PROPERTY CUDA_ARCHITECTURES 70-real 72-virtual)
958 Generates code for real architecture 70 and virtual architecture 72.
960 set_property(TARGET tgt PROPERTY CUDA_ARCHITECTURES OFF)
962 CMake will not pass any architecture flags to the compiler.
964 CMP0103
966 New in version 3.18.
967 Multiple calls to export() command with same FILE without APPEND is no
970 longer allowed.
971 In CMake 3.17 and below, multiple calls to export() command with the
973 same FILE without APPEND are accepted silently but only the last occur‐
974 rence is taken into account during the generation.
975 The OLD behavior for this policy is to ignore the multiple occurrences
977 of
978 export() command except the last one.
979 The NEW behavior of this policy is to raise an error on second call to
981 export() command with same FILE without APPEND.
982 This policy was introduced in CMake version 3.18. CMake version 3.22.0
984 warns when the policy is not set and uses OLD behavior. Use the
985 cmake_policy() command to set it to OLD or NEW explicitly.
986 NOTE:
988 The OLD behavior of a policy is deprecated by definition and may be
989 removed in a future version of CMake.
990
992 CMP0102
993 New in version 3.17.
994 The mark_as_advanced() command no longer creates a cache entry if one
997 does not already exist.
998 In CMake 3.16 and below, if a variable was not defined at all or just
1000 defined locally, the mark_as_advanced() command would create a new
1001 cache entry with an UNINITIALIZED type and no value. When a find_path()
1002 (or other similar find_ command) would next run, it would find this un‐
1003 defined cache entry and set it up with an empty string value. This
1004 process would end up deleting the local variable in the process (due to
1005 the way the cache works), effectively clearing any stored find_ results
1006 that were only available in the local scope.
1007 The OLD behavior for this policy is to create the empty cache defini‐
1009 tion. The NEW behavior of this policy is to ignore variables which do
1010 not already exist in the cache.
1011 This policy was introduced in CMake version 3.17. Use the cmake_pol‐
1013 icy() command to set it to OLD or NEW explicitly. Unlike many poli‐
1014 cies, CMake version 3.22.0 does not warn when this policy is not set
1015 and simply uses OLD behavior. See documentation of the CMAKE_POL‐
1016 ICY_WARNING_CMP0102 variable to control the warning.
1017 NOTE:
1019 The OLD behavior of a policy is deprecated by definition and may be
1020 removed in a future version of CMake.
1021 CMP0101
1023 New in version 3.17.
1024 target_compile_options() now honors BEFORE keyword in all scopes.
1027 In CMake 3.16 and below the target_compile_options() ignores the BEFORE
1029 keyword in private scope. CMake 3.17 and later honors BEFORE keyword in
1030 all scopes. This policy provides compatibility for projects that have
1031 not been updated to expect the new behavior.
1032 The OLD behavior for this policy is to not honor BEFORE keyword in pri‐
1034 vate scope. The NEW behavior of this policy is to honor BEFORE keyword
1035 in all scopes.
1036 This policy was introduced in CMake version 3.17. Use the cmake_pol‐
1038 icy() command to set it to OLD or NEW explicitly. Unlike many poli‐
1039 cies, CMake version 3.22.0 does not warn when this policy is not set
1040 and simply uses OLD behavior.
1041 NOTE:
1043 The OLD behavior of a policy is deprecated by definition and may be
1044 removed in a future version of CMake.
1045 CMP0100
1047 New in version 3.17.
1048 Let AUTOMOC and AUTOUIC process header files that end with a .hh exten‐
1051 sion.
1052 Since version 3.17, CMake processes header files that end with a .hh
1054 extension in AUTOMOC and AUTOUIC. In earlier CMake versions, these
1055 header files were ignored by AUTOMOC and AUTOUIC.
1056 This policy affects how header files that end with a .hh extension get
1058 treated in AUTOMOC and AUTOUIC.
1059 The OLD behavior for this policy is to ignore .hh header files in AUTO‐
1061 MOC and AUTOUIC.
1062 The NEW behavior for this policy is to process .hh header files in AU‐
1064 TOMOC and AUTOUIC just like other header files.
1065 NOTE:
1067 To silence the CMP0100 warning source files can be excluded from AU‐
1068 TOMOC and AUTOUIC processing by setting the source file properties
1069 SKIP_AUTOMOC, SKIP_AUTOUIC or SKIP_AUTOGEN.
1070 # Source skip example:
1072 set_property(SOURCE /path/to/file1.hh PROPERTY SKIP_AUTOMOC ON)
1073 set_property(SOURCE /path/to/file2.hh PROPERTY SKIP_AUTOUIC ON)
1074 set_property(SOURCE /path/to/file3.hh PROPERTY SKIP_AUTOGEN ON)
1075 This policy was introduced in CMake version 3.17.0. CMake version
1077 3.22.0 warns when the policy is not set and uses OLD behavior. Use the
1078 cmake_policy() command to set it to OLD or NEW explicitly.
1079 NOTE:
1081 The OLD behavior of a policy is deprecated by definition and may be
1082 removed in a future version of CMake.
1083 CMP0099
1085 New in version 3.17.
1086 Target link properties INTERFACE_LINK_OPTIONS, INTERFACE_LINK_DIRECTO‐
1089 RIES and INTERFACE_LINK_DEPENDS are now transitive over private depen‐
1090 dencies of static libraries.
1091 In CMake 3.16 and below the interface link properties attached to li‐
1093 braries are not propagated for private dependencies of static li‐
1094 braries. Only the libraries themselves are propagated to link the de‐
1095 pendent binary. CMake 3.17 and later prefer to propagate all interface
1096 link properties. This policy provides compatibility for projects that
1097 have not been updated to expect the new behavior.
1098 The OLD behavior for this policy is to not propagate interface link
1100 properties. The NEW behavior of this policy is to propagate interface
1101 link properties.
1102 This policy was introduced in CMake version 3.17. Use the cmake_pol‐
1104 icy() command to set it to OLD or NEW explicitly. Unlike many poli‐
1105 cies, CMake version 3.22.0 does not warn when this policy is not set
1106 and simply uses OLD behavior.
1107 NOTE:
1109 The OLD behavior of a policy is deprecated by definition and may be
1110 removed in a future version of CMake.
1111 CMP0098
1113 New in version 3.17.
1114 FindFLEX runs flex in directory CMAKE_CURRENT_BINARY_DIR when execut‐
1117 ing.
1118 The module provides a FLEX_TARGET macro which generates FLEX output.
1120 In CMake 3.16 and below the macro would generate a custom command that
1121 runs flex in the current source directory. CMake 3.17 and later prefer
1122 to run it in the build directory and use CMAKE_CURRENT_BINARY_DIR as
1123 the WORKING_DIRECTORY of its add_custom_command() invocation. This en‐
1124 sures that any implicitly generated file is written relative to the
1125 build tree rather than the source tree, unless the generated file is
1126 provided as absolute path.
1127 This policy provides compatibility for projects that have not been up‐
1129 dated to expect the new behavior.
1130 The OLD behavior for this policy is for FLEX_TARGET to use the current
1132 source directory for the WORKING_DIRECTORY and where to generate im‐
1133 plicit files. The NEW behavior of this policy is to use the current bi‐
1134 nary directory for the WORKING_DIRECTORY relative to which implicit
1135 files are generated unless provided as absolute path.
1136 This policy was introduced in CMake version 3.17. Use the cmake_pol‐
1138 icy() command to set it to OLD or NEW explicitly. Unlike many poli‐
1139 cies, CMake version 3.22.0 does not warn when this policy is not set
1140 and simply uses OLD behavior.
1141 NOTE:
1143 The OLD behavior of a policy is deprecated by definition and may be
1144 removed in a future version of CMake.
1145
1147 CMP0097
1148 New in version 3.16.
1149 ExternalProject_Add() with GIT_SUBMODULES "" initializes no submodules.
1152 The module provides a GIT_SUBMODULES option which controls what submod‐
1154 ules to initialize and update. Starting with CMake 3.16, explicitly
1155 setting GIT_SUBMODULES to an empty string means no submodules will be
1156 initialized or updated.
1157 This policy provides compatibility for projects that have not been up‐
1159 dated to expect the new behavior.
1160 The OLD behavior for this policy is for GIT_SUBMODULES when set to an
1162 empty string to initialize and update all git submodules. The NEW be‐
1163 havior for this policy is for GIT_SUBMODULES when set to an empty
1164 string to initialize and update no git submodules.
1165 This policy was introduced in CMake version 3.16. Use the cmake_pol‐
1167 icy() command to set it to OLD or NEW explicitly. Unlike most poli‐
1168 cies, CMake version 3.22.0 does not warn when this policy is not set
1169 and simply uses OLD behavior.
1170 CMP0096
1172 New in version 3.16.
1173 The project() command preserves leading zeros in version components.
1176 When a VERSION <major>[.<minor>[.<patch>[.<tweak>]]]] argument is given
1178 to the project() command, it stores the version string in the
1179 PROJECT_VERSION variable and stores individual integer version compo‐
1180 nents in PROJECT_VERSION_{MAJOR,MINOR,PATCH,TWEAK} variables (see pol‐
1181 icy CMP0048). CMake 3.15 and below dropped leading zeros from each
1182 component. CMake 3.16 and higher prefer to preserve leading zeros.
1183 This policy provides compatibility for projects that have not been up‐
1184 dated to expect the new behavior.
1185 The OLD behavior of this policy drops leading zeros in all components,
1187 e.g. such that version 1.07.06 becomes 1.7.6. The NEW behavior of
1188 this policy preserves the leading zeros in all components, such that
1189 version 1.07.06 remains unchanged.
1190 This policy was introduced in CMake version 3.16. Unlike many poli‐
1192 cies, CMake version 3.22.0 does not warn when this policy is not set
1193 and simply uses the OLD behavior. Use the cmake_policy() command to
1194 set it to OLD or NEW explicitly.
1195 NOTE:
1197 The OLD behavior of a policy is deprecated by definition and may be
1198 removed in a future version of CMake.
1199 CMP0095
1201 New in version 3.16.
1202 RPATH entries are properly escaped in the intermediary CMake install
1205 script.
1206 In CMake 3.15 and earlier, RPATH entries set via CMAKE_INSTALL_RPATH or
1208 via INSTALL_RPATH have not been escaped before being inserted into the
1209 cmake_install.cmake script. Dynamic linkers on ELF-based systems (e.g.
1210 Linux and FreeBSD) allow certain keywords in RPATH entries, such as
1211 ${ORIGIN} (More details are available in the ld.so man pages on those
1212 systems). The syntax of these keywords can match CMake's variable syn‐
1213 tax. In order to not be substituted (usually to an empty string) al‐
1214 ready by the intermediary cmake_install.cmake script, the user had to
1215 double-escape such RPATH keywords, e.g. set(CMAKE_INSTALL_RPATH
1216 "\\\${ORIGIN}/../lib"). Since the intermediary cmake_install.cmake
1217 script is an implementation detail of CMake, CMake 3.16 and later will
1218 make sure RPATH entries are inserted literally by escaping any coinci‐
1219 dental CMake syntax.
1220 The OLD behavior of this policy is to not escape RPATH entries in the
1222 intermediary cmake_install.cmake script. The NEW behavior is to prop‐
1223 erly escape coincidental CMake syntax in RPATH entries when generating
1224 the intermediary cmake_install.cmake script.
1225 This policy was introduced in CMake version 3.16. CMake version 3.22.0
1227 warns when the policy is not set and detected usage of CMake-like syn‐
1228 tax and uses OLD behavior. Use the cmake_policy() command to set it to
1229 OLD or NEW explicitly.
1230 NOTE:
1232 The OLD behavior of a policy is deprecated by definition and may be
1233 removed in a future version of CMake.
1234
1236 CMP0094
1237 New in version 3.15.
1238 Modules FindPython3, FindPython2 and FindPython use LOCATION for lookup
1241 strategy.
1242 Starting with CMake 3.15, Modules FindPython3, FindPython2 and Find‐
1244 Python set value LOCATION for, respectively, variables
1245 Python3_FIND_STRATEGY, Python2_FIND_STRATEGY and Python_FIND_STRATEGY.
1246 This policy provides compatibility with projects that expect the legacy
1247 behavior.
1248 The OLD behavior for this policy set value VERSION for variables
1250 Python3_FIND_STRATEGY, Python2_FIND_STRATEGY and Python_FIND_STRATEGY.
1251 This policy was introduced in CMake version 3.15. Use the cmake_pol‐
1253 icy() command to set it to OLD or NEW explicitly. Unlike many poli‐
1254 cies, CMake version 3.22.0 does not warn when this policy is not set
1255 and simply uses the OLD behavior.
1256 NOTE:
1258 The OLD behavior of a policy is deprecated by definition and may be
1259 removed in a future version of CMake.
1260 CMP0093
1262 New in version 3.15.
1263 FindBoost reports Boost_VERSION in x.y.z format.
1266 In CMake 3.14 and below the module would report the Boost version num‐
1268 ber as specified in the preprocessor definition BOOST_VERSION in the
1269 boost/version.hpp file. In CMake 3.15 and later it is preferred that
1270 the reported version number matches the x.y.z format reported by the
1271 CMake package shipped with Boost 1.70.0 and later. The macro value is
1272 still reported in the Boost_VERSION_MACRO variable.
1273 The OLD behavior for this policy is for FindBoost to report Boost_VER‐
1275 SION as specified in the preprocessor definition BOOST_VERSION in
1276 boost/version.hpp. The NEW behavior for this policy is for FindBoost to
1277 report Boost_VERSION in x.y.z format.
1278 This policy was introduced in CMake version 3.15. Use the cmake_pol‐
1280 icy() command to set it to OLD or NEW explicitly. Unlike many poli‐
1281 cies, CMake version 3.22.0 does not warn when this policy is not set
1282 and simply uses the OLD behavior.
1283 NOTE:
1285 The OLD behavior of a policy is deprecated by definition and may be
1286 removed in a future version of CMake.
1287 CMP0092
1289 New in version 3.15.
1290 MSVC warning flags are not in CMAKE_<LANG>_FLAGS by default.
1293 When using MSVC-like compilers in CMake 3.14 and below, warning flags
1295 like /W3 are added to CMAKE_<LANG>_FLAGS by default. This is problem‐
1296 atic for projects that want to choose a different warning level pro‐
1297 grammatically. In particular, it requires string editing of the
1298 CMAKE_<LANG>_FLAGS variables with knowledge of the CMake builtin de‐
1299 faults so they can be replaced.
1300 CMake 3.15 and above prefer to leave out warning flags from the value
1302 of CMAKE_<LANG>_FLAGS by default.
1303 This policy provides compatibility with projects that have not been up‐
1305 dated to expect the lack of warning flags. The policy setting takes
1306 effect as of the first project() or enable_language() command that ini‐
1307 tializes CMAKE_<LANG>_FLAGS for a given language <LANG>.
1308 NOTE:
1310 Once the policy has taken effect at the top of a project for a given
1311 language, that choice must be used throughout the tree for that lan‐
1312 guage. In projects that have nested projects in subdirectories, be
1313 sure to convert everything together.
1314 The OLD behavior for this policy is to place MSVC warning flags in the
1316 default CMAKE_<LANG>_FLAGS cache entries. The NEW behavior for this
1317 policy is to not place MSVC warning flags in the default cache entries.
1318 This policy was introduced in CMake version 3.15. Use the cmake_pol‐
1320 icy() command to set it to OLD or NEW explicitly. Unlike many poli‐
1321 cies, CMake version 3.22.0 does not warn when this policy is not set
1322 and simply uses OLD behavior.
1323 NOTE:
1325 The OLD behavior of a policy is deprecated by definition and may be
1326 removed in a future version of CMake.
1327 CMP0091
1329 New in version 3.15.
1330 MSVC runtime library flags are selected by an abstraction.
1333 Compilers targeting the MSVC ABI have flags to select the MSVC runtime
1335 library. Runtime library selection typically varies with build config‐
1336 uration because there is a separate runtime library for Debug builds.
1337 In CMake 3.14 and below, MSVC runtime library selection flags are added
1339 to the default CMAKE_<LANG>_FLAGS_<CONFIG> cache entries by CMake auto‐
1340 matically. This allows users to edit their cache entries to adjust the
1341 flags. However, the presence of such default flags is problematic for
1342 projects that want to choose a different runtime library programmati‐
1343 cally. In particular, it requires string editing of the
1344 CMAKE_<LANG>_FLAGS_<CONFIG> variables with knowledge of the CMake
1345 builtin defaults so they can be replaced.
1346 CMake 3.15 and above prefer to leave the MSVC runtime library selection
1348 flags out of the default CMAKE_<LANG>_FLAGS_<CONFIG> values and instead
1349 offer a first-class abstraction. The CMAKE_MSVC_RUNTIME_LIBRARY vari‐
1350 able and MSVC_RUNTIME_LIBRARY target property may be set to select the
1351 MSVC runtime library. If they are not set then CMake uses the default
1352 value MultiThreaded$<$<CONFIG:Debug>:Debug>DLL which is equivalent to
1353 the original flags.
1354 This policy provides compatibility with projects that have not been up‐
1356 dated to be aware of the abstraction. The policy setting takes effect
1357 as of the first project() or enable_language() command that enables a
1358 language whose compiler targets the MSVC ABI.
1359 NOTE:
1361 Once the policy has taken effect at the top of a project, that
1362 choice must be used throughout the tree. In projects that have
1363 nested projects in subdirectories, be sure to convert everything to‐
1364 gether.
1365 The OLD behavior for this policy is to place MSVC runtime library flags
1367 in the default CMAKE_<LANG>_FLAGS_<CONFIG> cache entries and ignore the
1368 CMAKE_MSVC_RUNTIME_LIBRARY abstraction. The NEW behavior for this pol‐
1369 icy is to not place MSVC runtime library flags in the default cache en‐
1370 tries and use the abstraction instead.
1371 This policy was introduced in CMake version 3.15. Use the cmake_pol‐
1373 icy() command to set it to OLD or NEW explicitly. Unlike many poli‐
1374 cies, CMake version 3.22.0 does not warn when this policy is not set
1375 and simply uses OLD behavior.
1376 NOTE:
1378 The OLD behavior of a policy is deprecated by definition and may be
1379 removed in a future version of CMake.
1380 CMP0090
1382 New in version 3.15.
1383 export(PACKAGE) does not populate package registry by default.
1386 In CMake 3.14 and below the export(PACKAGE) command populated the user
1388 package registry by default and users needed to set the CMAKE_EX‐
1389 PORT_NO_PACKAGE_REGISTRY to disable it, e.g. in automated build and
1390 packaging environments. Since the user package registry is stored out‐
1391 side the build tree, this side effect should not be enabled by default.
1392 Therefore CMake 3.15 and above prefer that export(PACKAGE) does nothing
1393 unless an explicit CMAKE_EXPORT_PACKAGE_REGISTRY variable is set to en‐
1394 able it. This policy provides compatibility with projects that have
1395 not been updated.
1396 The OLD behavior for this policy is for export(PACKAGE) command to pop‐
1398 ulate the user package registry unless CMAKE_EXPORT_NO_PACKAGE_REGISTRY
1399 is enabled. The NEW behavior is for export(PACKAGE) command to do
1400 nothing unless the CMAKE_EXPORT_PACKAGE_REGISTRY is enabled.
1401 This policy was introduced in CMake version 3.15. Use the cmake_pol‐
1403 icy() command to set it to OLD or NEW explicitly. Unlike most poli‐
1404 cies, CMake version 3.22.0 does not warn when this policy is not set
1405 and simply uses OLD behavior.
1406 NOTE:
1408 The OLD behavior of a policy is deprecated by definition and may be
1409 removed in a future version of CMake.
1410 CMP0089
1412 New in version 3.15.
1413 Compiler id for IBM Clang-based XL compilers is now XLClang.
1416 CMake 3.15 and above recognize that IBM's Clang-based XL compilers that
1418 define __ibmxl__ are a new front-end distinct from xlc with a different
1419 command line and set of capabilities. CMake now prefers to present
1420 this to projects by setting the CMAKE_<LANG>_COMPILER_ID variable to
1421 XLClang instead of XL. However, existing projects may assume the com‐
1422 piler id for Clang-based XL is just XL as it was in CMake versions
1423 prior to 3.15. Therefore this policy determines for Clang-based XL
1424 compilers which compiler id to report in the CMAKE_<LANG>_COMPILER_ID
1425 variable after language <LANG> is enabled by the project() or en‐
1426 able_language() command. The policy must be set prior to the invoca‐
1427 tion of either command.
1428 The OLD behavior for this policy is to use compiler id XL. The NEW be‐
1430 havior for this policy is to use compiler id XLClang.
1431 This policy was introduced in CMake version 3.15. Use the cmake_pol‐
1433 icy() command to set this policy to OLD or NEW explicitly. Unlike most
1434 policies, CMake version 3.22.0 does not warn by default when this pol‐
1435 icy is not set and simply uses OLD behavior. See documentation of the
1436 CMAKE_POLICY_WARNING_CMP0089 variable to control the warning.
1437 NOTE:
1439 The OLD behavior of a policy is deprecated by definition and may be
1440 removed in a future version of CMake.
1441
1443 CMP0088
1444 New in version 3.14.
1445 FindBISON runs bison in CMAKE_CURRENT_BINARY_DIR when executing.
1448 The module provides a BISON_TARGET macro which generates BISON output.
1450 In CMake 3.13 and below the macro would generate a custom command that
1451 runs bison in the source directory. CMake 3.14 and later prefer to run
1452 it in the build directory and use CMAKE_CURRENT_BINARY_DIR as the WORK‐
1453 ING_DIRECTORY of its add_custom_command() invocation. This ensures
1454 that any implicitly generated file is written to the build tree rather
1455 than the source.
1456 This policy provides compatibility for projects that have not been up‐
1458 dated to expect the new behavior.
1459 The OLD behavior for this policy is for BISON_TARGET to use the current
1461 source directory for the WORKING_DIRECTORY and where to generate im‐
1462 plicit files. The NEW behavior of this policy is to use the current bi‐
1463 nary directory for the WORKING_DIRECTORY and where to generate implicit
1464 files.
1465 This policy was introduced in CMake version 3.14. Use the cmake_pol‐
1467 icy() command to set it to OLD or NEW explicitly. Unlike most poli‐
1468 cies, CMake version 3.22.0 does not warn when this policy is not set
1469 and simply uses OLD behavior.
1470 NOTE:
1472 The OLD behavior of a policy is deprecated by definition and may be
1473 removed in a future version of CMake.
1474 CMP0087
1476 New in version 3.14.
1477 install(CODE) and install(SCRIPT) support generator expressions.
1480 In CMake 3.13 and earlier, install(CODE) and install(SCRIPT) did not
1482 evaluate generator expressions. CMake 3.14 and later will evaluate
1483 generator expressions for install(CODE) and install(SCRIPT).
1484 The OLD behavior of this policy is for install(CODE) and in‐
1486 stall(SCRIPT) to not evaluate generator expressions. The NEW behavior
1487 is to evaluate generator expressions for install(CODE) and in‐
1488 stall(SCRIPT).
1489 Note that it is the value of this policy setting at the end of the di‐
1491 rectory scope that is important, not its setting at the time of the
1492 call to install(CODE) or install(SCRIPT). This has implications for
1493 calling these commands from places that have their own policy scope but
1494 not their own directory scope (e.g. from files brought in via include()
1495 rather than add_subdirectory()).
1496 This policy was introduced in CMake version 3.14. CMake version 3.22.0
1498 warns when the policy is not set and uses OLD behavior. Use the
1499 cmake_policy() command to set it to OLD or NEW explicitly.
1500 NOTE:
1502 The OLD behavior of a policy is deprecated by definition and may be
1503 removed in a future version of CMake.
1504 CMP0086
1506 New in version 3.14.
1507 UseSWIG honors SWIG_MODULE_NAME via -module flag.
1510 Starting with CMake 3.14, UseSWIG passes option -module <module_name>
1512 to SWIG compiler if the file property SWIG_MODULE_NAME is specified.
1513 This policy provides compatibility with projects that expect the legacy
1514 behavior.
1515 The OLD behavior for this policy is to never pass -module option. The
1517 NEW behavior is to pass -module option to SWIG compiler if SWIG_MOD‐
1518 ULE_NAME is specified.
1519 This policy was introduced in CMake version 3.14. CMake version 3.22.0
1521 warns when the policy is not set and uses OLD behavior. Use the
1522 cmake_policy() command to set it to OLD or NEW explicitly.
1523 NOTE:
1525 The OLD behavior of a policy is deprecated by definition and may be
1526 removed in a future version of CMake.
1527 CMP0085
1529 New in version 3.14.
1530 $<IN_LIST:...> handles empty list items.
1533 In CMake 3.13 and lower, the $<IN_LIST:...> generator expression always
1535 returned 0 if the first argument was empty, even if the list contained
1536 an empty item. This behavior is inconsistent with the IN_LIST behavior
1537 of if(), which this generator expression is meant to emulate. CMake
1538 3.14 and later handles this case correctly.
1539 The OLD behavior of this policy is for $<IN_LIST:...> to always return
1541 0 if the first argument is empty. The NEW behavior is to return 1 if
1542 the first argument is empty and the list contains an empty item.
1543 This policy was introduced in CMake version 3.14. CMake version 3.22.0
1545 warns when the policy is not set and uses OLD behavior. Use the
1546 cmake_policy() command to set it to OLD or NEW explicitly.
1547 NOTE:
1549 The OLD behavior of a policy is deprecated by definition and may be
1550 removed in a future version of CMake.
1551 CMP0084
1553 New in version 3.14.
1554 The FindQt module does not exist for find_package().
1557 The existence of FindQt means that for Qt upstream to provide package
1559 config files that can be found by find_package(Qt), the consuming
1560 project has to explicitly specify find_package(Qt CONFIG). Removing
1561 this module gives Qt a path forward for exporting its own config files
1562 which can easily be found by consuming projects.
1563 This policy pretends that CMake's internal FindQt module does not exist
1565 for find_package(). If a project really wants to use Qt 3 or 4, it can
1566 call find_package(Qt[34]), include(FindQt), or add FindQt to their
1567 CMAKE_MODULE_PATH.
1568 The OLD behavior of this policy is for FindQt to exist for find_pack‐
1570 age(). The NEW behavior is to pretend that it doesn't exist for
1571 find_package().
1572 This policy was introduced in CMake version 3.14. CMake version 3.22.0
1574 warns when the policy is not set and uses OLD behavior. Use the
1575 cmake_policy() command to set it to OLD or NEW explicitly.
1576 NOTE:
1578 The OLD behavior of a policy is deprecated by definition and may be
1579 removed in a future version of CMake.
1580 CMP0083
1582 New in version 3.14.
1583 To control generation of Position Independent Executable (PIE) or not,
1586 some flags are required at link time.
1587 CMake 3.13 and lower did not add these link flags when POSITION_INDE‐
1589 PENDENT_CODE is set.
1590 The OLD behavior for this policy is to not manage PIE link flags. The
1592 NEW behavior is to add link flags if POSITION_INDEPENDENT_CODE is set:
1593 • Set to TRUE: flags to produce a position independent executable are
1595 passed to the linker step. For example -pie for GCC.
1596 • Set to FALSE: flags not to produce a position independent executable
1598 are passed to the linker step. For example -no-pie for GCC.
1599 • Not set: no flags are passed to the linker step.
1601 Since a given linker may not support PIE flags in all environments in
1603 which it is used, it is the project's responsibility to use the Check‐
1604 PIESupported module to check for support to ensure that the POSI‐
1605 TION_INDEPENDENT_CODE target property for executables will be honored
1606 at link time.
1607 This policy was introduced in CMake version 3.14. Use the cmake_pol‐
1609 icy() command to set it to OLD or NEW explicitly. Unlike most poli‐
1610 cies, CMake version 3.22.0 does not warn when this policy is not set
1611 and simply uses OLD behavior.
1612 NOTE:
1614 Android platform has a special handling of PIE so it is not required
1615 to use the CheckPIESupported module to ensure flags are passed to
1616 the linker.
1617 NOTE:
1619 The OLD behavior of a policy is deprecated by definition and may be
1620 removed in a future version of CMake.
1621 Examples
1623 Behave like CMake 3.13 and do not apply any PIE flags at link stage.
1624 cmake_minimum_required(VERSION 3.13)
1626 project(foo)
1627 # ...
1629 add_executable(foo ...)
1631 set_property(TARGET foo PROPERTY POSITION_INDEPENDENT_CODE TRUE)
1632 Use the CheckPIESupported module to detect whether PIE is supported by
1634 the current linker and environment. Apply PIE flags only if the linker
1635 supports them.
1636 cmake_minimum_required(VERSION 3.14) # CMP0083 NEW
1638 project(foo)
1639 include(CheckPIESupported)
1641 check_pie_supported()
1642 # ...
1644 add_executable(foo ...)
1646 set_property(TARGET foo PROPERTY POSITION_INDEPENDENT_CODE TRUE)
1647 CMP0082
1649 New in version 3.14.
1650 Install rules from add_subdirectory() calls are interleaved with those
1653 in caller.
1654 CMake 3.13 and lower ran the install rules from add_subdirectory() af‐
1656 ter all other install rules, even if add_subdirectory() was called be‐
1657 fore the other install rules. CMake 3.14 and above prefer to inter‐
1658 leave these add_subdirectory() install rules with the others so that
1659 they are run in the order they are declared. This policy provides com‐
1660 patibility for projects that have not been updated to expect the new
1661 behavior.
1662 The OLD behavior for this policy is to run the install rules from
1664 add_subdirectory() after the other install rules. The NEW behavior for
1665 this policy is to run all install rules in the order they are declared.
1666 This policy was introduced in CMake version 3.14. Unlike most poli‐
1668 cies, CMake version 3.22.0 does not warn by default when this policy is
1669 not set and simply uses OLD behavior. See documentation of the
1670 CMAKE_POLICY_WARNING_CMP0082 variable to control the warning.
1671 NOTE:
1673 The OLD behavior of a policy is deprecated by definition and may be
1674 removed in a future version of CMake.
1675
1677 CMP0081
1678 New in version 3.13.
1679 Relative paths not allowed in LINK_DIRECTORIES target property.
1682 CMake 3.12 and lower allowed the LINK_DIRECTORIES directory property to
1684 contain relative paths. The base path for such relative entries is not
1685 well defined. CMake 3.13 and later will issue a FATAL_ERROR if the
1686 LINK_DIRECTORIES target property (which is initialized by the LINK_DI‐
1687 RECTORIES directory property) contains a relative path.
1688 The OLD behavior for this policy is not to warn about relative paths in
1690 the LINK_DIRECTORIES target property. The NEW behavior for this policy
1691 is to issue a FATAL_ERROR if LINK_DIRECTORIES contains a relative path.
1692 This policy was introduced in CMake version 3.13. CMake version 3.22.0
1694 warns when the policy is not set and uses OLD behavior. Use the
1695 cmake_policy() command to set it to OLD or NEW explicitly.
1696 NOTE:
1698 The OLD behavior of a policy is deprecated by definition and may be
1699 removed in a future version of CMake.
1700 CMP0080
1702 New in version 3.13.
1703 BundleUtilities cannot be included at configure time.
1706 The macros provided by BundleUtilities are intended to be invoked at
1708 install time rather than at configure time, because they depend on the
1709 listed targets already existing at the time they are invoked. If they
1710 are invoked at configure time, the targets haven't been built yet, and
1711 the commands will fail.
1712 This policy restricts the inclusion of BundleUtilities to cmake -P
1714 style scripts and install rules. Specifically, it looks for the pres‐
1715 ence of CMAKE_GENERATOR and throws a fatal error if it exists.
1716 The OLD behavior of this policy is to allow BundleUtilities to be in‐
1718 cluded at configure time. The NEW behavior of this policy is to disal‐
1719 low such inclusion.
1720 This policy was introduced in CMake version 3.13. CMake version 3.22.0
1722 warns when the policy is not set and uses OLD behavior. Use the
1723 cmake_policy() command to set it to OLD or NEW explicitly.
1724 NOTE:
1726 The OLD behavior of a policy is deprecated by definition and may be
1727 removed in a future version of CMake.
1728 CMP0079
1730 New in version 3.13.
1731 target_link_libraries() allows use with targets in other directories.
1734 Prior to CMake 3.13 the target_link_libraries() command did not accept
1736 targets not created in the calling directory as its first argument for
1737 calls that update the LINK_LIBRARIES of the target itself. It did ac‐
1738 cidentally accept targets from other directories on calls that only up‐
1739 date the INTERFACE_LINK_LIBRARIES, but would simply add entries to the
1740 property as if the call were made in the original directory. Thus link
1741 interface libraries specified this way were always looked up by genera‐
1742 tors in the scope of the original target rather than in the scope that
1743 called target_link_libraries().
1744 CMake 3.13 now allows the target_link_libraries() command to be called
1746 from any directory to add link dependencies and link interface li‐
1747 braries to targets created in other directories. The entries are added
1748 to LINK_LIBRARIES and INTERFACE_LINK_LIBRARIES using a special (inter‐
1749 nal) suffix to tell the generators to look up the names in the calling
1750 scope rather than the scope that created the target.
1751 This policy provides compatibility with projects that already use tar‐
1753 get_link_libraries() with the INTERFACE keyword on a target in another
1754 directory to add INTERFACE_LINK_LIBRARIES entries to be looked up in
1755 the target's directory. Such projects should be updated to be aware of
1756 the new scoping rules in that case.
1757 The OLD behavior of this policy is to disallow target_link_libraries()
1759 calls naming targets from another directory except in the previously
1760 accidentally allowed case of using the INTERFACE keyword only. The NEW
1761 behavior of this policy is to allow all such calls but use the new
1762 scoping rules.
1763 This policy was introduced in CMake version 3.13. CMake version 3.22.0
1765 warns when the policy is not set and uses OLD behavior. Use the
1766 cmake_policy() command to set it to OLD or NEW explicitly.
1767 NOTE:
1769 The OLD behavior of a policy is deprecated by definition and may be
1770 removed in a future version of CMake.
1771 CMP0078
1773 New in version 3.13.
1774 UseSWIG generates standard target names.
1777 Starting with CMake 3.13, UseSWIG generates now standard target names.
1779 This policy provides compatibility with projects that expect the legacy
1780 behavior.
1781 The OLD behavior for this policy relies on UseSWIG_TARGET_NAME_PREFER‐
1783 ENCE variable that can be used to specify an explicit preference. The
1784 value may be one of:
1785 • LEGACY: legacy strategy is applied. Variable SWIG_MOD‐
1787 ULE_<name>_REAL_NAME must be used to get real target name. This is
1788 the default if not specified.
1789 • STANDARD: target name matches specified name.
1791 This policy was introduced in CMake version 3.13. CMake version 3.22.0
1793 warns when the policy is not set and uses OLD behavior. Use the
1794 cmake_policy() command to set it to OLD or NEW explicitly.
1795 NOTE:
1797 The OLD behavior of a policy is deprecated by definition and may be
1798 removed in a future version of CMake.
1799 CMP0077
1801 New in version 3.13.
1802 option() honors normal variables.
1805 The option() command is typically used to create a cache entry to allow
1807 users to set the option. However, there are cases in which a normal
1808 (non-cached) variable of the same name as the option may be defined by
1809 the project prior to calling the option() command. For example, a
1810 project that embeds another project as a subdirectory may want to
1811 hard-code options of the subproject to build the way it needs.
1812 For historical reasons in CMake 3.12 and below the option() command re‐
1814 moves a normal (non-cached) variable of the same name when:
1815 • a cache entry of the specified name does not exist at all, or
1817 • a cache entry of the specified name exists but has not been given a
1819 type (e.g. via -D<name>=ON on the command line).
1820 In both of these cases (typically on the first run in a new build
1822 tree), the option() command gives the cache entry type BOOL and removes
1823 any normal (non-cached) variable of the same name. In the remaining
1824 case that the cache entry of the specified name already exists and has
1825 a type (typically on later runs in a build tree), the option() command
1826 changes nothing and any normal variable of the same name remains set.
1827 In CMake 3.13 and above the option() command prefers to do nothing when
1829 a normal variable of the given name already exists. It does not create
1830 or update a cache entry or remove the normal variable. The new behav‐
1831 ior is consistent between the first and later runs in a build tree.
1832 This policy provides compatibility with projects that have not been up‐
1833 dated to expect the new behavior.
1834 When the option() command sees a normal variable of the given name:
1836 • The OLD behavior for this policy is to proceed even when a normal
1838 variable of the same name exists. If the cache entry does not al‐
1839 ready exist and have a type then it is created and/or given a type
1840 and the normal variable is removed.
1841 • The NEW behavior for this policy is to do nothing when a normal vari‐
1843 able of the same name exists. The normal variable is not removed.
1844 The cache entry is not created or updated and is ignored if it ex‐
1845 ists.
1846 See CMP0126 for a similar policy for the set(CACHE) command, but note
1848 that there are some differences in NEW behavior between the two poli‐
1849 cies.
1850 This policy was introduced in CMake version 3.13. CMake version 3.22.0
1852 warns when the policy is not set and uses OLD behavior. Use the
1853 cmake_policy() command to set it to OLD or NEW explicitly.
1854 NOTE:
1856 The OLD behavior of a policy is deprecated by definition and may be
1857 removed in a future version of CMake.
1858 CMP0076
1860 New in version 3.13.
1861 The target_sources() command converts relative paths to absolute.
1864 In CMake 3.13 and above, the target_sources() command now converts rel‐
1866 ative source file paths to absolute paths in the following cases:
1867 • Source files are added to the target's INTERFACE_SOURCES property.
1869 • The target's SOURCE_DIR property differs from CMAKE_CUR‐
1871 RENT_SOURCE_DIR.
1872 A path that begins with a generator expression is always left unmodi‐
1874 fied.
1875 This policy provides compatibility with projects that have not been up‐
1877 dated to expect this behavior. The OLD behavior for this policy is to
1878 leave all relative source file paths unmodified. The NEW behavior of
1879 this policy is to convert relative paths to absolute according to above
1880 rules.
1881 This policy was introduced in CMake version 3.13. CMake version 3.22.0
1883 warns when the policy is not set and uses OLD behavior. Use the
1884 cmake_policy() command to set it to OLD or NEW explicitly.
1885 NOTE:
1887 The OLD behavior of a policy is deprecated by definition and may be
1888 removed in a future version of CMake.
1889
1891 CMP0075
1892 New in version 3.12.
1893 Include file check macros honor CMAKE_REQUIRED_LIBRARIES.
1896 In CMake 3.12 and above, the
1898 • check_include_file macro in the CheckIncludeFile module, the
1900 • check_include_file_cxx macro in the CheckIncludeFileCXX module, and
1902 the
1903 • check_include_files macro in the CheckIncludeFiles module
1905 now prefer to link the check executable to the libraries listed in the
1907 CMAKE_REQUIRED_LIBRARIES variable. This policy provides compatibility
1908 with projects that have not been updated to expect this behavior.
1909 The OLD behavior for this policy is to ignore CMAKE_REQUIRED_LIBRARIES
1911 in the include file check macros. The NEW behavior of this policy is
1912 to honor CMAKE_REQUIRED_LIBRARIES in the include file check macros.
1913 This policy was introduced in CMake version 3.12. CMake version 3.22.0
1915 warns when the policy is not set and uses OLD behavior. Use the
1916 cmake_policy() command to set it to OLD or NEW explicitly.
1917 NOTE:
1919 The OLD behavior of a policy is deprecated by definition and may be
1920 removed in a future version of CMake.
1921 CMP0074
1923 New in version 3.12.
1924 find_package() uses <PackageName>_ROOT variables.
1927 In CMake 3.12 and above the find_package(<PackageName>) command now
1929 searches prefixes specified by the <PackageName>_ROOT CMake variable
1930 and the <PackageName>_ROOT environment variable. Package roots are
1931 maintained as a stack so nested calls to all find_* commands inside
1932 find modules and config packages also search the roots as prefixes.
1933 This policy provides compatibility with projects that have not been up‐
1934 dated to avoid using <PackageName>_ROOT variables for other purposes.
1935 The OLD behavior for this policy is to ignore <PackageName>_ROOT vari‐
1937 ables. The NEW behavior for this policy is to use <PackageName>_ROOT
1938 variables.
1939 This policy was introduced in CMake version 3.12. CMake version 3.22.0
1941 warns when the policy is not set and uses OLD behavior. Use the
1942 cmake_policy() command to set it to OLD or NEW explicitly.
1943 NOTE:
1945 The OLD behavior of a policy is deprecated by definition and may be
1946 removed in a future version of CMake.
1947 CMP0073
1949 New in version 3.12.
1950 Do not produce legacy _LIB_DEPENDS cache entries.
1953 Ancient CMake versions once used <tgt>_LIB_DEPENDS cache entries to
1955 propagate library link dependencies. This has long been done by other
1956 means, leaving the export_library_dependencies() command as the only
1957 user of these values. That command has long been disallowed by policy
1958 CMP0033, but the <tgt>_LIB_DEPENDS cache entries were left for compati‐
1959 bility with possible non-standard uses by projects.
1960 CMake 3.12 and above now prefer to not produce these cache entries at
1962 all. This policy provides compatibility with projects that have not
1963 been updated to avoid using them.
1964 The OLD behavior for this policy is to set <tgt>_LIB_DEPENDS cache en‐
1966 tries. The NEW behavior for this policy is to not set them.
1967 This policy was introduced in CMake version 3.12. Use the cmake_pol‐
1969 icy() command to set it to OLD or NEW explicitly. Unlike most poli‐
1970 cies, CMake version 3.22.0 does not warn when this policy is not set
1971 and simply uses OLD behavior.
1972 NOTE:
1974 The OLD behavior of a policy is deprecated by definition and may be
1975 removed in a future version of CMake.
1976
1978 CMP0072
1979 New in version 3.11.
1980 FindOpenGL prefers GLVND by default when available.
1983 The FindOpenGL module provides an OpenGL::GL target and an OPENGL_LI‐
1985 BRARIES variable for projects to use for legacy GL interfaces. When
1986 both a legacy GL library (e.g. libGL.so) and GLVND libraries for OpenGL
1987 and GLX (e.g. libOpenGL.so and libGLX.so) are available, the module
1988 must choose between them. It documents an OpenGL_GL_PREFERENCE vari‐
1989 able that can be used to specify an explicit preference. When no such
1990 preference is set, the module must choose a default preference.
1991 CMake 3.11 and above prefer to choose GLVND libraries. This policy
1993 provides compatibility with projects that expect the legacy GL library
1994 to be used.
1995 The OLD behavior for this policy is to set OpenGL_GL_PREFERENCE to
1997 LEGACY. The NEW behavior for this policy is to set OpenGL_GL_PREFER‐
1998 ENCE to GLVND.
1999 This policy was introduced in CMake version 3.11. CMake version 3.22.0
2001 warns when the policy is not set and uses OLD behavior. Use the
2002 cmake_policy() command to set it to OLD or NEW explicitly.
2003 NOTE:
2005 The OLD behavior of a policy is deprecated by definition and may be
2006 removed in a future version of CMake.
2007
2009 CMP0071
2010 New in version 3.10.
2011 Let AUTOMOC and AUTOUIC process GENERATED files.
2014 Since version 3.10, CMake processes regular and GENERATED source files
2016 in AUTOMOC and AUTOUIC. In earlier CMake versions, only regular source
2017 files were processed. GENERATED source files were ignored silently.
2018 This policy affects how source files that are GENERATED get treated in
2020 AUTOMOC and AUTOUIC.
2021 The OLD behavior for this policy is to ignore GENERATED source files in
2023 AUTOMOC and AUTOUIC.
2024 The NEW behavior for this policy is to process GENERATED source files
2026 in AUTOMOC and AUTOUIC just like regular source files.
2027 NOTE:
2029 To silence the CMP0071 warning source files can be excluded from AU‐
2030 TOMOC and AUTOUIC processing by setting the source file properties
2031 SKIP_AUTOMOC, SKIP_AUTOUIC or SKIP_AUTOGEN.
2032 Source skip example:
2034 # ...
2036 set_property(SOURCE /path/to/file1.h PROPERTY SKIP_AUTOMOC ON)
2037 set_property(SOURCE /path/to/file2.h PROPERTY SKIP_AUTOUIC ON)
2038 set_property(SOURCE /path/to/file3.h PROPERTY SKIP_AUTOGEN ON)
2039 # ...
2040 This policy was introduced in CMake version 3.10. CMake version 3.22.0
2042 warns when the policy is not set and uses OLD behavior. Use the
2043 cmake_policy() command to set it to OLD or NEW explicitly.
2044 NOTE:
2046 The OLD behavior of a policy is deprecated by definition and may be
2047 removed in a future version of CMake.
2048 CMP0070
2050 New in version 3.10.
2051 Define file(GENERATE) behavior for relative paths.
2054 CMake 3.10 and newer define that relative paths given to INPUT and OUT‐
2056 PUT arguments of file(GENERATE) are interpreted relative to the current
2057 source and binary directories, respectively. CMake 3.9 and lower did
2058 not define any behavior for relative paths but did not diagnose them
2059 either and accidentally treated them relative to the process working
2060 directory. Policy CMP0070 provides compatibility with projects that
2061 used the old undefined behavior.
2062 This policy affects behavior of relative paths given to file(GENERATE).
2064 The OLD behavior for this policy is to treat the paths relative to the
2065 working directory of CMake. The NEW behavior for this policy is to in‐
2066 terpret relative paths with respect to the current source or binary di‐
2067 rectory of the caller.
2068 This policy was introduced in CMake version 3.10. CMake version 3.22.0
2070 warns when the policy is not set and uses OLD behavior. Use the
2071 cmake_policy() command to set it to OLD or NEW explicitly.
2072 NOTE:
2074 The OLD behavior of a policy is deprecated by definition and may be
2075 removed in a future version of CMake.
2076
2078 CMP0069
2079 New in version 3.9.
2080 INTERPROCEDURAL_OPTIMIZATION is enforced when enabled.
2083 CMake 3.9 and newer prefer to add IPO flags whenever the INTERPROCEDU‐
2085 RAL_OPTIMIZATION target property is enabled and produce an error if
2086 flags are not known to CMake for the current compiler. Since a given
2087 compiler may not support IPO flags in all environments in which it is
2088 used, it is now the project's responsibility to use the CheckIPOSup‐
2089 ported module to check for support before enabling the INTERPROCEDU‐
2090 RAL_OPTIMIZATION target property. This approach allows a project to
2091 conditionally activate IPO when supported. It also allows an end user
2092 to set the CMAKE_INTERPROCEDURAL_OPTIMIZATION variable in an environ‐
2093 ment known to support IPO even if the project does not enable the prop‐
2094 erty.
2095 Since CMake 3.8 and lower only honored INTERPROCEDURAL_OPTIMIZATION for
2097 the Intel compiler on Linux, some projects may unconditionally enable
2098 the target property. Policy CMP0069 provides compatibility with such
2099 projects.
2100 This policy takes effect whenever the IPO property is enabled. The OLD
2102 behavior for this policy is to add IPO flags only for Intel compiler on
2103 Linux. The NEW behavior for this policy is to add IPO flags for the
2104 current compiler or produce an error if CMake does not know the flags.
2105 This policy was introduced in CMake version 3.9. CMake version 3.22.0
2107 warns when the policy is not set and uses OLD behavior. Use the
2108 cmake_policy() command to set it to OLD or NEW explicitly.
2109 NOTE:
2111 The OLD behavior of a policy is deprecated by definition and may be
2112 removed in a future version of CMake.
2113 Examples
2115 Behave like CMake 3.8 and do not apply any IPO flags except for Intel
2116 compiler on Linux:
2117 cmake_minimum_required(VERSION 3.8)
2119 project(foo)
2120 # ...
2122 set_property(TARGET ... PROPERTY INTERPROCEDURAL_OPTIMIZATION TRUE)
2124 Use the CheckIPOSupported module to detect whether IPO is supported by
2126 the current compiler, environment, and CMake version. Produce a fatal
2127 error if support is not available:
2128 cmake_minimum_required(VERSION 3.9) # CMP0069 NEW
2130 project(foo)
2131 include(CheckIPOSupported)
2133 check_ipo_supported()
2134 # ...
2136 set_property(TARGET ... PROPERTY INTERPROCEDURAL_OPTIMIZATION TRUE)
2138 Apply IPO flags only if compiler supports it:
2140 cmake_minimum_required(VERSION 3.9) # CMP0069 NEW
2142 project(foo)
2143 include(CheckIPOSupported)
2145 # ...
2147 check_ipo_supported(RESULT result)
2149 if(result)
2150 set_property(TARGET ... PROPERTY INTERPROCEDURAL_OPTIMIZATION TRUE)
2151 endif()
2152 Apply IPO flags without any checks. This may lead to build errors if
2154 IPO is not supported by the compiler in the current environment. Pro‐
2155 duce an error if CMake does not know IPO flags for the current com‐
2156 piler:
2157 cmake_minimum_required(VERSION 3.9) # CMP0069 NEW
2159 project(foo)
2160 # ...
2162 set_property(TARGET ... PROPERTY INTERPROCEDURAL_OPTIMIZATION TRUE)
2164 CMP0068
2166 New in version 3.9.
2167 RPATH settings on macOS do not affect install_name.
2170 CMake 3.9 and newer remove any effect the following settings may have
2172 on the install_name of a target on macOS:
2173 • BUILD_WITH_INSTALL_RPATH target property
2175 • SKIP_BUILD_RPATH target property
2177 • CMAKE_SKIP_RPATH variable
2179 • CMAKE_SKIP_INSTALL_RPATH variable
2181 Previously, setting BUILD_WITH_INSTALL_RPATH had the effect of setting
2183 both the install_name of a target to INSTALL_NAME_DIR and the RPATH to
2184 INSTALL_RPATH. In CMake 3.9, it only affects setting of RPATH. How‐
2185 ever, if one wants INSTALL_NAME_DIR to apply to the target in the build
2186 tree, one may set BUILD_WITH_INSTALL_NAME_DIR.
2187 If SKIP_BUILD_RPATH, CMAKE_SKIP_RPATH or CMAKE_SKIP_INSTALL_RPATH were
2189 used to strip the directory portion of the install_name of a target,
2190 one may set INSTALL_NAME_DIR="" instead.
2191 The OLD behavior of this policy is to use the RPATH settings for in‐
2193 stall_name on macOS. The NEW behavior of this policy is to ignore the
2194 RPATH settings for install_name on macOS.
2195 This policy was introduced in CMake version 3.9. CMake version 3.22.0
2197 warns when the policy is not set and uses OLD behavior. Use the
2198 cmake_policy() command to set it to OLD or NEW explicitly.
2199 NOTE:
2201 The OLD behavior of a policy is deprecated by definition and may be
2202 removed in a future version of CMake.
2203
2205 CMP0067
2206 New in version 3.8.
2207 Honor language standard in try_compile() source-file signature.
2210 The try_compile() source file signature is intended to allow callers to
2212 check whether they will be able to compile a given source file with the
2213 current toolchain. In order to match compiler behavior, any language
2214 standard mode should match. However, CMake 3.7 and below did not do
2215 this. CMake 3.8 and above prefer to honor the language standard set‐
2216 tings for C, CXX (C++), and CUDA using the values of the variables:
2217 • CMAKE_C_STANDARD
2219 • CMAKE_C_STANDARD_REQUIRED
2221 • CMAKE_C_EXTENSIONS
2223 • CMAKE_CXX_STANDARD
2225 • CMAKE_CXX_STANDARD_REQUIRED
2227 • CMAKE_CXX_EXTENSIONS
2229 • CMAKE_CUDA_STANDARD
2231 • CMAKE_CUDA_STANDARD_REQUIRED
2233 • CMAKE_CUDA_EXTENSIONS
2235 This policy provides compatibility for projects that do not expect the
2237 language standard settings to be used automatically.
2238 The OLD behavior of this policy is to ignore language standard setting
2240 variables when generating the try_compile test project. The NEW behav‐
2241 ior of this policy is to honor language standard setting variables.
2242 This policy was introduced in CMake version 3.8. Unlike most policies,
2244 CMake version 3.22.0 does not warn by default when this policy is not
2245 set and simply uses OLD behavior. See documentation of the CMAKE_POL‐
2246 ICY_WARNING_CMP0067 variable to control the warning.
2247 NOTE:
2249 The OLD behavior of a policy is deprecated by definition and may be
2250 removed in a future version of CMake.
2251
2253 CMP0066
2254 New in version 3.7.
2255 Honor per-config flags in try_compile() source-file signature.
2258 The source file signature of the try_compile() command uses the value
2260 of the CMAKE_<LANG>_FLAGS variable in the test project so that the test
2261 compilation works as it would in the main project. However, CMake 3.6
2262 and below do not also honor config-specific compiler flags such as
2263 those in the CMAKE_<LANG>_FLAGS_DEBUG variable. CMake 3.7 and above
2264 prefer to honor config-specific compiler flags too. This policy pro‐
2265 vides compatibility for projects that do not expect config-specific
2266 compiler flags to be used.
2267 The OLD behavior of this policy is to ignore config-specific flag vari‐
2269 ables like CMAKE_<LANG>_FLAGS_DEBUG and only use CMake's built-in de‐
2270 faults for the current compiler and platform.
2271 The NEW behavior of this policy is to honor config-specific flag vari‐
2273 abldes like CMAKE_<LANG>_FLAGS_DEBUG.
2274 This policy was introduced in CMake version 3.7. Unlike most policies,
2276 CMake version 3.22.0 does not warn by default when this policy is not
2277 set and simply uses OLD behavior. See documentation of the CMAKE_POL‐
2278 ICY_WARNING_CMP0066 variable to control the warning.
2279 NOTE:
2281 The OLD behavior of a policy is deprecated by definition and may be
2282 removed in a future version of CMake.
2283
2285 CMP0065
2286 New in version 3.4.
2287 Do not add flags to export symbols from executables without the EN‐
2290 ABLE_EXPORTS target property.
2291 CMake 3.3 and below, for historical reasons, always linked executables
2293 on some platforms with flags like -rdynamic to export symbols from the
2294 executables for use by any plugins they may load via dlopen. CMake 3.4
2295 and above prefer to do this only for executables that are explicitly
2296 marked with the ENABLE_EXPORTS target property.
2297 The OLD behavior of this policy is to always use the additional link
2299 flags when linking executables regardless of the value of the EN‐
2300 ABLE_EXPORTS target property.
2301 The NEW behavior of this policy is to only use the additional link
2303 flags when linking executables if the ENABLE_EXPORTS target property is
2304 set to True.
2305 This policy was introduced in CMake version 3.4. Unlike most policies,
2307 CMake version 3.22.0 does not warn by default when this policy is not
2308 set and simply uses OLD behavior. See documentation of the CMAKE_POL‐
2309 ICY_WARNING_CMP0065 variable to control the warning.
2310 NOTE:
2312 The OLD behavior of a policy is deprecated by definition and may be
2313 removed in a future version of CMake.
2314 CMP0064
2316 New in version 3.4.
2317 Recognize TEST as a operator for the if() command.
2320 The TEST operator was added to the if() command to determine if a given
2322 test name was created by the add_test() command.
2323 The OLD behavior for this policy is to ignore the TEST operator. The
2325 NEW behavior is to interpret the TEST operator.
2326 This policy was introduced in CMake version 3.4. CMake version 3.22.0
2328 warns when the policy is not set and uses OLD behavior. Use the
2329 cmake_policy() command to set it to OLD or NEW explicitly.
2330 NOTE:
2332 The OLD behavior of a policy is deprecated by definition and may be
2333 removed in a future version of CMake.
2334
2336 CMP0063
2337 New in version 3.3.
2338 Honor visibility properties for all target types.
2341 The <LANG>_VISIBILITY_PRESET and VISIBILITY_INLINES_HIDDEN target prop‐
2343 erties affect visibility of symbols during dynamic linking. When first
2344 introduced these properties affected compilation of sources only in
2345 shared libraries, module libraries, and executables with the ENABLE_EX‐
2346 PORTS property set. This was sufficient for the basic use cases of
2347 shared libraries and executables with plugins. However, some sources
2348 may be compiled as part of static libraries or object libraries and
2349 then linked into a shared library later. CMake 3.3 and above prefer to
2350 honor these properties for sources compiled in all target types. This
2351 policy preserves compatibility for projects expecting the properties to
2352 work only for some target types.
2353 The OLD behavior for this policy is to ignore the visibility properties
2355 for static libraries, object libraries, and executables without ex‐
2356 ports. The NEW behavior for this policy is to honor the visibility
2357 properties for all target types.
2358 This policy was introduced in CMake version 3.3. CMake version 3.22.0
2360 warns when the policy is not set and uses OLD behavior. Use the
2361 cmake_policy() command to set it to OLD or NEW explicitly.
2362 NOTE:
2364 The OLD behavior of a policy is deprecated by definition and may be
2365 removed in a future version of CMake.
2366 CMP0062
2368 New in version 3.3.
2369 Disallow install() of export() result.
2372 The export() command generates a file containing Imported Targets,
2374 which is suitable for use from the build directory. It is not suitable
2375 for installation because it contains absolute paths to buildsystem lo‐
2376 cations, and is particular to a single build configuration.
2377 The install(EXPORT) generates and installs files which contain Imported
2379 Targets. These files are generated with relative paths (unless the
2380 user specifies absolute paths), and are designed for multi-configura‐
2381 tion use. See Creating Packages for more.
2382 CMake 3.3 no longer allows the use of the install(FILES) command with
2384 the result of the export() command.
2385 The OLD behavior for this policy is to allow installing the result of
2387 an export() command. The NEW behavior for this policy is not to allow
2388 installing the result of an export() command.
2389 This policy was introduced in CMake version 3.3. CMake version 3.22.0
2391 warns when the policy is not set and uses OLD behavior. Use the
2392 cmake_policy() command to set it to OLD or NEW explicitly.
2393 NOTE:
2395 The OLD behavior of a policy is deprecated by definition and may be
2396 removed in a future version of CMake.
2397 CMP0061
2399 New in version 3.3.
2400 CTest does not by default tell make to ignore errors (-i).
2403 The ctest_build() and build_command() commands no longer generate build
2405 commands for Makefile Generators with the -i option. Previously this
2406 was done to help build as much of tested projects as possible. How‐
2407 ever, this behavior is not consistent with other generators and also
2408 causes the return code of the make tool to be meaningless.
2409 Of course users may still add this option manually by setting
2411 CTEST_BUILD_COMMAND or the MAKECOMMAND cache entry. See the CTest
2412 Build Step MakeCommand setting documentation for their effects.
2413 The OLD behavior for this policy is to add -i to make calls in CTest.
2415 The NEW behavior for this policy is to not add -i.
2416 This policy was introduced in CMake version 3.3. Unlike most policies,
2418 CMake version 3.22.0 does not warn when this policy is not set and sim‐
2419 ply uses OLD behavior.
2420 NOTE:
2422 The OLD behavior of a policy is deprecated by definition and may be
2423 removed in a future version of CMake.
2424 CMP0060
2426 New in version 3.3.
2427 Link libraries by full path even in implicit directories.
2430 Policy CMP0003 was introduced with the intention of always linking li‐
2432 brary files by full path when a full path is given to the tar‐
2433 get_link_libraries() command. However, on some platforms (e.g. HP-UX)
2434 the compiler front-end adds alternative library search paths for the
2435 current architecture (e.g. /usr/lib/<arch> has alternatives to li‐
2436 braries in /usr/lib for the current architecture). On such platforms
2437 the find_library() may find a library such as /usr/lib/libfoo.so that
2438 does not belong to the current architecture.
2439 Prior to policy CMP0003 projects would still build in such cases be‐
2441 cause the incorrect library path would be converted to -lfoo on the
2442 link line and the linker would find the proper library in the arch-spe‐
2443 cific search path provided by the compiler front-end implicitly. At
2444 the time we chose to remain compatible with such projects by always
2445 converting library files found in implicit link directories to -lfoo
2446 flags to ask the linker to search for them. This approach allowed ex‐
2447 isting projects to continue to build while still linking to libraries
2448 outside implicit link directories via full path (such as those in the
2449 build tree).
2450 CMake does allow projects to override this behavior by using an IM‐
2452 PORTED library target with its IMPORTED_LOCATION property set to the
2453 desired full path to a library file. In fact, many Find Modules are
2454 learning to provide Imported Targets instead of just the traditional
2455 Foo_LIBRARIES variable listing library files. However, this makes the
2456 link line generated for a library found by a Find Module depend on
2457 whether it is linked through an imported target or not, which is incon‐
2458 sistent. Furthermore, this behavior has been a source of confusion be‐
2459 cause the generated link line for a library file depends on its loca‐
2460 tion. It is also problematic for projects trying to link statically
2461 because flags like -Wl,-Bstatic -lfoo -Wl,-Bdynamic may be used to help
2462 the linker select libfoo.a instead of libfoo.so but then leak dynamic
2463 linking to following libraries. (See the LINK_SEARCH_END_STATIC target
2464 property for a solution typically used for that problem.)
2465 When the special case for libraries in implicit link directories was
2467 first introduced the list of implicit link directories was simply
2468 hard-coded (e.g. /lib, /usr/lib, and a few others). Since that time,
2469 CMake has learned to detect the implicit link directories used by the
2470 compiler front-end. If necessary, the find_library() command could be
2471 taught to use this information to help find libraries of the proper ar‐
2472 chitecture.
2473 For these reasons, CMake 3.3 and above prefer to drop the special case
2475 and link libraries by full path even when they are in implicit link di‐
2476 rectories. Policy CMP0060 provides compatibility for existing
2477 projects.
2478 The OLD behavior for this policy is to ask the linker to search for li‐
2480 braries whose full paths are known to be in implicit link directories.
2481 The NEW behavior for this policy is to link libraries by full path even
2482 if they are in implicit link directories.
2483 This policy was introduced in CMake version 3.3. Unlike most policies,
2485 CMake version 3.22.0 does not warn by default when this policy is not
2486 set and simply uses OLD behavior. See documentation of the CMAKE_POL‐
2487 ICY_WARNING_CMP0060 variable to control the warning.
2488 NOTE:
2490 The OLD behavior of a policy is deprecated by definition and may be
2491 removed in a future version of CMake.
2492 CMP0059
2494 New in version 3.3.
2495 Do not treat DEFINITIONS as a built-in directory property.
2498 CMake 3.3 and above no longer make a list of definitions available
2500 through the DEFINITIONS directory property. The COMPILE_DEFINITIONS
2501 directory property may be used instead.
2502 The OLD behavior for this policy is to provide the list of flags given
2504 so far to the add_definitions() command. The NEW behavior is to behave
2505 as a normal user-defined directory property.
2506 This policy was introduced in CMake version 3.3. CMake version 3.22.0
2508 warns when the policy is not set and uses OLD behavior. Use the
2509 cmake_policy() command to set it to OLD or NEW explicitly.
2510 NOTE:
2512 The OLD behavior of a policy is deprecated by definition and may be
2513 removed in a future version of CMake.
2514 CMP0058
2516 New in version 3.3.
2517 Ninja requires custom command byproducts to be explicit.
2520 When an intermediate file generated during the build is consumed by an
2522 expensive operation or a large tree of dependents, one may reduce the
2523 work needed for an incremental rebuild by updating the file timestamp
2524 only when its content changes. With this approach the generation rule
2525 must have a separate output file that is always updated with a new
2526 timestamp that is newer than any dependencies of the rule so that the
2527 build tool re-runs the rule only when the input changes. We refer to
2528 the separate output file as a rule's witness and the generated file as
2529 a rule's byproduct.
2530 Byproducts may not be listed as outputs because their timestamps are
2532 allowed to be older than the inputs. No build tools (like make) that
2533 existed when CMake was designed have a way to express byproducts.
2534 Therefore CMake versions prior to 3.2 had no way to specify them.
2535 Projects typically left byproducts undeclared in the rules that gener‐
2536 ate them. For example:
2537 add_custom_command(
2539 OUTPUT witness.txt
2540 COMMAND ${CMAKE_COMMAND} -E copy_if_different
2541 ${CMAKE_CURRENT_SOURCE_DIR}/input.txt
2542 byproduct.txt # timestamp may not change
2543 COMMAND ${CMAKE_COMMAND} -E touch witness.txt
2544 DEPENDS ${CMAKE_CURRENT_SOURCE_DIR}/input.txt
2545 )
2546 add_custom_target(Provider DEPENDS witness.txt)
2547 add_custom_command(
2548 OUTPUT generated.c
2549 COMMAND expensive-task -i byproduct.txt -o generated.c
2550 DEPENDS ${CMAKE_CURRENT_BINARY_DIR}/byproduct.txt
2551 )
2552 add_library(Consumer generated.c)
2553 add_dependencies(Consumer Provider)
2554 This works well for all generators except Ninja. The Ninja build tool
2556 sees a rule listing byproduct.txt as a dependency and no rule listing
2557 it as an output. Ninja then complains that there is no way to satisfy
2558 the dependency and stops building even though there are order-only de‐
2559 pendencies that ensure byproduct.txt will exist before its consumers
2560 need it. See discussion of this problem in Ninja Issue 760 for further
2561 details on why Ninja works this way.
2562 Instead of leaving byproducts undeclared in the rules that generate
2564 them, Ninja expects byproducts to be listed along with other outputs.
2565 Such rules may be marked with a restat option that tells Ninja to check
2566 the timestamps of outputs after the rules run. This prevents byprod‐
2567 ucts whose timestamps do not change from causing their dependents to
2568 re-build unnecessarily.
2569 Since the above approach does not tell CMake what custom command gener‐
2571 ates byproduct.txt, the Ninja generator does not have enough informa‐
2572 tion to add the byproduct as an output of any rule. CMake 2.8.12 and
2573 above work around this problem and allow projects using the above ap‐
2574 proach to build by generating phony build rules to tell Ninja to toler‐
2575 ate such missing files. However, this workaround prevents Ninja from
2576 diagnosing a dependency that is really missing. It also works poorly
2577 in in-source builds where every custom command dependency, even on
2578 source files, needs to be treated this way because CMake does not have
2579 enough information to know which files are generated as byproducts of
2580 custom commands.
2581 CMake 3.2 introduced the BYPRODUCTS option to the add_custom_command()
2583 and add_custom_target() commands. This option allows byproducts to be
2584 specified explicitly:
2585 add_custom_command(
2587 OUTPUT witness.txt
2588 BYPRODUCTS byproduct.txt # explicit byproduct specification
2589 COMMAND ${CMAKE_COMMAND} -E copy_if_different
2590 ${CMAKE_CURRENT_SOURCE_DIR}/input.txt
2591 byproduct.txt # timestamp may not change
2592 ...
2593 The BYPRODUCTS option is used by the Ninja generator to list byproducts
2595 among the outputs of the custom commands that generate them, and is ig‐
2596 nored by other generators.
2597 CMake 3.3 and above prefer to require projects to specify custom com‐
2599 mand byproducts explicitly so that it can avoid using the phony rule
2600 workaround altogether. Policy CMP0058 was introduced to provide com‐
2601 patibility with existing projects that still need the workaround.
2602 This policy has no effect on generators other than Ninja. The OLD be‐
2604 havior for this policy is to generate Ninja phony rules for unknown de‐
2605 pendencies in the build tree. The NEW behavior for this policy is to
2606 not generate these and instead require projects to specify custom com‐
2607 mand BYPRODUCTS explicitly.
2608 This policy was introduced in CMake version 3.3. CMake version 3.22.0
2610 warns when it sees unknown dependencies in out-of-source build trees if
2611 the policy is not set and then uses OLD behavior. Use the cmake_pol‐
2612 icy() command to set the policy to OLD or NEW explicitly. The policy
2613 setting must be in scope at the end of the top-level CMakeLists.txt
2614 file of the project and has global effect.
2615 NOTE:
2617 The OLD behavior of a policy is deprecated by definition and may be
2618 removed in a future version of CMake.
2619 CMP0057
2621 New in version 3.3.
2622 Support new if() IN_LIST operator.
2625 CMake 3.3 adds support for the new IN_LIST operator.
2627 The OLD behavior for this policy is to ignore the IN_LIST operator.
2629 The NEW behavior is to interpret the IN_LIST operator.
2630 This policy was introduced in CMake version 3.3. CMake version 3.22.0
2632 warns when the policy is not set and uses OLD behavior. Use the
2633 cmake_policy() command to set it to OLD or NEW explicitly.
2634 NOTE:
2636 The OLD behavior of a policy is deprecated by definition and may be
2637 removed in a future version of CMake.
2638
2640 CMP0056
2641 New in version 3.2.
2642 Honor link flags in try_compile() source-file signature.
2645 The try_compile() command source-file signature generates a CMake‐
2647 Lists.txt file to build the source file into an executable. In order
2648 to compile the source the same way as it might be compiled by the call‐
2649 ing project, the generated project sets the value of the
2650 CMAKE_<LANG>_FLAGS variable to that in the calling project. The value
2651 of the CMAKE_EXE_LINKER_FLAGS variable may be needed in some cases too,
2652 but CMake 3.1 and lower did not set it in the generated project. CMake
2653 3.2 and above prefer to set it so that linker flags are honored as well
2654 as compiler flags. This policy provides compatibility with the pre-3.2
2655 behavior.
2656 The OLD behavior for this policy is to not set the value of the
2658 CMAKE_EXE_LINKER_FLAGS variable in the generated test project. The NEW
2659 behavior for this policy is to set the value of the
2660 CMAKE_EXE_LINKER_FLAGS variable in the test project to the same as it
2661 is in the calling project.
2662 If the project code does not set the policy explicitly, users may set
2664 it on the command line by defining the CMAKE_POLICY_DEFAULT_CMP0056
2665 variable in the cache.
2666 This policy was introduced in CMake version 3.2. Unlike most policies,
2668 CMake version 3.22.0 does not warn by default when this policy is not
2669 set and simply uses OLD behavior. See documentation of the CMAKE_POL‐
2670 ICY_WARNING_CMP0056 variable to control the warning.
2671 NOTE:
2673 The OLD behavior of a policy is deprecated by definition and may be
2674 removed in a future version of CMake.
2675 CMP0055
2677 New in version 3.2.
2678 Strict checking for the break() command.
2681 CMake 3.1 and lower allowed calls to the break() command outside of a
2683 loop context and also ignored any given arguments. This was undefined
2684 behavior.
2685 The OLD behavior for this policy is to allow break() to be placed out‐
2687 side of loop contexts and ignores any arguments. The NEW behavior for
2688 this policy is to issue an error if a misplaced break or any arguments
2689 are found.
2690 This policy was introduced in CMake version 3.2. CMake version 3.22.0
2692 warns when the policy is not set and uses OLD behavior. Use the
2693 cmake_policy() command to set it to OLD or NEW explicitly.
2694 NOTE:
2696 The OLD behavior of a policy is deprecated by definition and may be
2697 removed in a future version of CMake.
2698
2700 CMP0054
2701 New in version 3.1.
2702 Only interpret if() arguments as variables or keywords when unquoted.
2705 CMake 3.1 and above no longer implicitly dereference variables or in‐
2707 terpret keywords in an if() command argument when it is a Quoted Argu‐
2708 ment or a Bracket Argument.
2709 The OLD behavior for this policy is to dereference variables and inter‐
2711 pret keywords even if they are quoted or bracketed. The NEW behavior
2712 is to not dereference variables or interpret keywords that have been
2713 quoted or bracketed.
2714 Given the following partial example:
2716 set(A E)
2718 set(E "")
2719 if("${A}" STREQUAL "")
2721 message("Result is TRUE before CMake 3.1 or when CMP0054 is OLD")
2722 else()
2723 message("Result is FALSE in CMake 3.1 and above if CMP0054 is NEW")
2724 endif()
2725 After explicit expansion of variables this gives:
2727 if("E" STREQUAL "")
2729 With the policy set to OLD implicit expansion reduces this semantically
2731 to:
2732 if("" STREQUAL "")
2734 With the policy set to NEW the quoted arguments will not be further
2736 dereferenced:
2737 if("E" STREQUAL "")
2739 This policy was introduced in CMake version 3.1. CMake version 3.22.0
2741 warns when the policy is not set and uses OLD behavior. Use the
2742 cmake_policy() command to set it to OLD or NEW explicitly.
2743 NOTE:
2745 The OLD behavior of a policy is deprecated by definition and may be
2746 removed in a future version of CMake.
2747 CMP0053
2749 New in version 3.1.
2750 Simplify variable reference and escape sequence evaluation.
2753 CMake 3.1 introduced a much faster implementation of evaluation of the
2755 Variable References and Escape Sequences documented in the cmake-lan‐
2756 guage(7) manual. While the behavior is identical to the legacy imple‐
2757 mentation in most cases, some corner cases were cleaned up to simplify
2758 the behavior. Specifically:
2759 • Expansion of @VAR@ reference syntax defined by the configure_file()
2761 and string(CONFIGURE) commands is no longer performed in other con‐
2762 texts.
2763 • Literal ${VAR} reference syntax may contain only alphanumeric charac‐
2765 ters (A-Z, a-z, 0-9) and the characters _, ., /, -, and +. Note that
2766 $ is technically allowed in the NEW behavior, but is invalid for OLD
2767 behavior. This is due to an oversight during the implementation of
2768 CMP0053 and its use as a literal variable reference is discouraged
2769 for this reason. Variables with other characters in their name may
2770 still be referenced indirectly, e.g.
2771 set(varname "otherwise & disallowed $ characters")
2773 message("${${varname}}")
2774 • The setting of policy CMP0010 is not considered, so improper variable
2776 reference syntax is always an error.
2777 • More characters are allowed to be escaped in variable names. Previ‐
2779 ously, only ()#" \@^ were valid characters to escape. Now any non-al‐
2780 phanumeric, non-semicolon, non-NUL character may be escaped following
2781 the escape_identity production in the Escape Sequences section of the
2782 cmake-language(7) manual.
2783 The OLD behavior for this policy is to honor the legacy behavior for
2785 variable references and escape sequences. The NEW behavior is to use
2786 the simpler variable expansion and escape sequence evaluation rules.
2787 This policy was introduced in CMake version 3.1. CMake version 3.22.0
2789 warns when the policy is not set and uses OLD behavior. Use the
2790 cmake_policy() command to set it to OLD or NEW explicitly.
2791 NOTE:
2793 The OLD behavior of a policy is deprecated by definition and may be
2794 removed in a future version of CMake.
2795 CMP0052
2797 New in version 3.1.
2798 Reject source and build dirs in installed INTERFACE_INCLUDE_DIRECTO‐
2801 RIES.
2802 CMake 3.0 and lower allowed subdirectories of the source directory or
2804 build directory to be in the INTERFACE_INCLUDE_DIRECTORIES of installed
2805 and exported targets, if the directory was also a subdirectory of the
2806 installation prefix. This makes the installation depend on the exis‐
2807 tence of the source dir or binary dir, and the installation will be
2808 broken if either are removed after installation.
2809 See Include Directories and Usage Requirements for more on specifying
2811 include directories for targets.
2812 The OLD behavior for this policy is to export the content of the INTER‐
2814 FACE_INCLUDE_DIRECTORIES with the source or binary directory. The NEW
2815 behavior for this policy is to issue an error if such a directory is
2816 used.
2817 This policy was introduced in CMake version 3.1. CMake version 3.22.0
2819 warns when the policy is not set and uses OLD behavior. Use the
2820 cmake_policy() command to set it to OLD or NEW explicitly.
2821 NOTE:
2823 The OLD behavior of a policy is deprecated by definition and may be
2824 removed in a future version of CMake.
2825 CMP0051
2827 New in version 3.1.
2828 List TARGET_OBJECTS in SOURCES target property.
2831 CMake 3.0 and lower did not include the TARGET_OBJECTS generator ex‐
2833 pression when returning the SOURCES target property.
2834 Configure-time CMake code is not able to handle generator expressions.
2836 If using the SOURCES target property at configure time, it may be nec‐
2837 essary to first remove generator expressions using the
2838 string(GENEX_STRIP) command. Generate-time CMake code such as
2839 file(GENERATE) can handle the content without stripping.
2840 The OLD behavior for this policy is to omit TARGET_OBJECTS expressions
2842 from the SOURCES target property. The NEW behavior for this policy is
2843 to include TARGET_OBJECTS expressions in the output.
2844 This policy was introduced in CMake version 3.1. CMake version 3.22.0
2846 warns when the policy is not set and uses OLD behavior. Use the
2847 cmake_policy() command to set it to OLD or NEW explicitly.
2848 NOTE:
2850 The OLD behavior of a policy is deprecated by definition and may be
2851 removed in a future version of CMake.
2852
2854 CMP0050
2855 Disallow add_custom_command SOURCE signatures.
2856 CMake 2.8.12 and lower allowed a signature for add_custom_command()
2858 which specified an input to a command. This was undocumented behavior.
2859 Modern use of CMake associates custom commands with their output,
2860 rather than their input.
2861 The OLD behavior for this policy is to allow the use of add_custom_com‐
2863 mand() SOURCE signatures. The NEW behavior for this policy is to issue
2864 an error if such a signature is used.
2865 This policy was introduced in CMake version 3.0. CMake version 3.22.0
2867 warns when the policy is not set and uses OLD behavior. Use the
2868 cmake_policy() command to set it to OLD or NEW explicitly.
2869 NOTE:
2871 The OLD behavior of a policy is deprecated by definition and may be
2872 removed in a future version of CMake.
2873 CMP0049
2875 Do not expand variables in target source entries.
2876 CMake 2.8.12 and lower performed an extra layer of variable expansion
2878 when evaluating source file names:
2879 set(a_source foo.c)
2881 add_executable(foo \${a_source})
2882 This was undocumented behavior.
2884 The OLD behavior for this policy is to expand such variables when pro‐
2886 cessing the target sources. The NEW behavior for this policy is to is‐
2887 sue an error if such variables need to be expanded.
2888 This policy was introduced in CMake version 3.0. CMake version 3.22.0
2890 warns when the policy is not set and uses OLD behavior. Use the
2891 cmake_policy() command to set it to OLD or NEW explicitly.
2892 NOTE:
2894 The OLD behavior of a policy is deprecated by definition and may be
2895 removed in a future version of CMake.
2896 CMP0048
2898 The project() command manages VERSION variables.
2899 CMake version 3.0 introduced the VERSION option of the project() com‐
2901 mand to specify a project version as well as the name. In order to
2902 keep PROJECT_VERSION and related variables consistent with variable
2903 PROJECT_NAME it is necessary to set the VERSION variables to the empty
2904 string when no VERSION is given to project(). However, this can change
2905 behavior for existing projects that set VERSION variables themselves
2906 since project() may now clear them. This policy controls the behavior
2907 for compatibility with such projects.
2908 The OLD behavior for this policy is to leave VERSION variables un‐
2910 touched. The NEW behavior for this policy is to set VERSION as docu‐
2911 mented by the project() command.
2912 This policy was introduced in CMake version 3.0. CMake version 3.22.0
2914 warns when the policy is not set and uses OLD behavior. Use the
2915 cmake_policy() command to set it to OLD or NEW explicitly.
2916 NOTE:
2918 The OLD behavior of a policy is deprecated by definition and may be
2919 removed in a future version of CMake.
2920 CMP0047
2922 Use QCC compiler id for the qcc drivers on QNX.
2923 CMake 3.0 and above recognize that the QNX qcc compiler driver is dif‐
2925 ferent from the GNU compiler. CMake now prefers to present this to
2926 projects by setting the CMAKE_<LANG>_COMPILER_ID variable to QCC in‐
2927 stead of GNU. However, existing projects may assume the compiler id
2928 for QNX qcc is just GNU as it was in CMake versions prior to 3.0.
2929 Therefore this policy determines for QNX qcc which compiler id to re‐
2930 port in the CMAKE_<LANG>_COMPILER_ID variable after language <LANG> is
2931 enabled by the project() or enable_language() command. The policy must
2932 be set prior to the invocation of either command.
2933 The OLD behavior for this policy is to use the GNU compiler id for the
2935 qcc and QCC compiler drivers. The NEW behavior for this policy is to
2936 use the QCC compiler id for those drivers.
2937 This policy was introduced in CMake version 3.0. Use the cmake_pol‐
2939 icy() command to set this policy to OLD or NEW explicitly. Unlike most
2940 policies, CMake version 3.22.0 does not warn by default when this pol‐
2941 icy is not set and simply uses OLD behavior. See documentation of the
2942 CMAKE_POLICY_WARNING_CMP0047 variable to control the warning.
2943 NOTE:
2945 The OLD behavior of a policy is deprecated by definition and may be
2946 removed in a future version of CMake.
2947 CMP0046
2949 Error on non-existent dependency in add_dependencies.
2950 CMake 2.8.12 and lower silently ignored non-existent dependencies
2952 listed in the add_dependencies() command.
2953 The OLD behavior for this policy is to silently ignore non-existent de‐
2955 pendencies. The NEW behavior for this policy is to report an error if
2956 non-existent dependencies are listed in the add_dependencies() command.
2957 This policy was introduced in CMake version 3.0. CMake version 3.22.0
2959 warns when the policy is not set and uses OLD behavior. Use the
2960 cmake_policy() command to set it to OLD or NEW explicitly.
2961 NOTE:
2963 The OLD behavior of a policy is deprecated by definition and may be
2964 removed in a future version of CMake.
2965 CMP0045
2967 Error on non-existent target in get_target_property.
2968 In CMake 2.8.12 and lower, the get_target_property() command accepted a
2970 non-existent target argument without issuing any error or warning. The
2971 result variable is set to a -NOTFOUND value.
2972 The OLD behavior for this policy is to issue no warning and set the re‐
2974 sult variable to a -NOTFOUND value. The NEW behavior for this policy
2975 is to issue a FATAL_ERROR if the command is called with a non-existent
2976 target.
2977 This policy was introduced in CMake version 3.0. CMake version 3.22.0
2979 warns when the policy is not set and uses OLD behavior. Use the
2980 cmake_policy() command to set it to OLD or NEW explicitly.
2981 NOTE:
2983 The OLD behavior of a policy is deprecated by definition and may be
2984 removed in a future version of CMake.
2985 CMP0044
2987 Case sensitive <LANG>_COMPILER_ID generator expressions
2988 CMake 2.8.12 introduced the <LANG>_COMPILER_ID generator expressions to
2990 allow comparison of the CMAKE_<LANG>_COMPILER_ID with a test value.
2991 The possible valid values are lowercase, but the comparison with the
2992 test value was performed case-insensitively.
2993 The OLD behavior for this policy is to perform a case-insensitive com‐
2995 parison with the value in the <LANG>_COMPILER_ID expression. The NEW
2996 behavior for this policy is to perform a case-sensitive comparison with
2997 the value in the <LANG>_COMPILER_ID expression.
2998 This policy was introduced in CMake version 3.0. CMake version 3.22.0
3000 warns when the policy is not set and uses OLD behavior. Use the
3001 cmake_policy() command to set it to OLD or NEW explicitly.
3002 NOTE:
3004 The OLD behavior of a policy is deprecated by definition and may be
3005 removed in a future version of CMake.
3006 CMP0043
3008 Ignore COMPILE_DEFINITIONS_<Config> properties
3009 CMake 2.8.12 and lower allowed setting the COMPILE_DEFINITIONS_<CONFIG>
3011 target property and COMPILE_DEFINITIONS_<CONFIG> directory property to
3012 apply configuration-specific compile definitions.
3013 Since CMake 2.8.10, the COMPILE_DEFINITIONS property has supported gen‐
3015 erator expressions for setting configuration-dependent content. The
3016 continued existence of the suffixed variables is redundant, and causes
3017 a maintenance burden. Population of the COMPILE_DEFINITIONS_DEBUG
3018 property may be replaced with a population of COMPILE_DEFINITIONS di‐
3019 rectly or via target_compile_definitions():
3020 # Old Interfaces:
3022 set_property(TARGET tgt APPEND PROPERTY
3023 COMPILE_DEFINITIONS_DEBUG DEBUG_MODE
3024 )
3025 set_property(DIRECTORY APPEND PROPERTY
3026 COMPILE_DEFINITIONS_DEBUG DIR_DEBUG_MODE
3027 )
3028 # New Interfaces:
3030 set_property(TARGET tgt APPEND PROPERTY
3031 COMPILE_DEFINITIONS $<$<CONFIG:Debug>:DEBUG_MODE>
3032 )
3033 target_compile_definitions(tgt PRIVATE $<$<CONFIG:Debug>:DEBUG_MODE>)
3034 set_property(DIRECTORY APPEND PROPERTY
3035 COMPILE_DEFINITIONS $<$<CONFIG:Debug>:DIR_DEBUG_MODE>
3036 )
3037 The OLD behavior for this policy is to consume the content of the suf‐
3039 fixed COMPILE_DEFINITIONS_<CONFIG> target property when generating the
3040 compilation command. The NEW behavior for this policy is to ignore the
3041 content of the COMPILE_DEFINITIONS_<CONFIG> target property .
3042 This policy was introduced in CMake version 3.0. CMake version 3.22.0
3044 warns when the policy is not set and uses OLD behavior. Use the
3045 cmake_policy() command to set it to OLD or NEW explicitly.
3046 NOTE:
3048 The OLD behavior of a policy is deprecated by definition and may be
3049 removed in a future version of CMake.
3050 CMP0042
3052 MACOSX_RPATH is enabled by default.
3053 CMake 2.8.12 and newer has support for using @rpath in a target's in‐
3055 stall name. This was enabled by setting the target property MA‐
3056 COSX_RPATH. The @rpath in an install name is a more flexible and pow‐
3057 erful mechanism than @executable_path or @loader_path for locating
3058 shared libraries.
3059 CMake 3.0 and later prefer this property to be ON by default. Projects
3061 wanting @rpath in a target's install name may remove any setting of the
3062 INSTALL_NAME_DIR and CMAKE_INSTALL_NAME_DIR variables.
3063 This policy was introduced in CMake version 3.0. CMake version 3.22.0
3065 warns when the policy is not set and uses OLD behavior. Use the
3066 cmake_policy() command to set it to OLD or NEW explicitly.
3067 NOTE:
3069 The OLD behavior of a policy is deprecated by definition and may be
3070 removed in a future version of CMake.
3071 CMP0041
3073 Error on relative include with generator expression.
3074 Diagnostics in CMake 2.8.12 and lower silently ignored an entry in the
3076 INTERFACE_INCLUDE_DIRECTORIES of a target if it contained a generator
3077 expression at any position.
3078 The path entries in that target property should not be relative.
3080 High-level API should ensure that by adding either a source directory
3081 or a install directory prefix, as appropriate.
3082 As an additional diagnostic, the INTERFACE_INCLUDE_DIRECTORIES gener‐
3084 ated on an IMPORTED target for the install location should not contain
3085 paths in the source directory or the build directory.
3086 The OLD behavior for this policy is to ignore relative path entries if
3088 they contain a generator expression. The NEW behavior for this policy
3089 is to report an error if a generator expression appears in another lo‐
3090 cation and the path is relative.
3091 This policy was introduced in CMake version 3.0. CMake version 3.22.0
3093 warns when the policy is not set and uses OLD behavior. Use the
3094 cmake_policy() command to set it to OLD or NEW explicitly.
3095 NOTE:
3097 The OLD behavior of a policy is deprecated by definition and may be
3098 removed in a future version of CMake.
3099 CMP0040
3101 The target in the TARGET signature of add_custom_command() must exist
3102 and must be defined in the current directory.
3103 CMake 2.8.12 and lower silently ignored a custom command created with
3105 the TARGET signature of add_custom_command() if the target is unknown
3106 or was defined outside the current directory.
3107 The OLD behavior for this policy is to ignore custom commands for un‐
3109 known targets. The NEW behavior for this policy is to report an error
3110 if the target referenced in add_custom_command() is unknown or was de‐
3111 fined outside the current directory.
3112 This policy was introduced in CMake version 3.0. CMake version 3.22.0
3114 warns when the policy is not set and uses OLD behavior. Use the
3115 cmake_policy() command to set it to OLD or NEW explicitly.
3116 NOTE:
3118 The OLD behavior of a policy is deprecated by definition and may be
3119 removed in a future version of CMake.
3120 CMP0039
3122 Utility targets may not have link dependencies.
3123 CMake 2.8.12 and lower allowed using utility targets in the left hand
3125 side position of the target_link_libraries() command. This is an indi‐
3126 cator of a bug in user code.
3127 The OLD behavior for this policy is to ignore attempts to set the link
3129 libraries of utility targets. The NEW behavior for this policy is to
3130 report an error if an attempt is made to set the link libraries of a
3131 utility target.
3132 This policy was introduced in CMake version 3.0. CMake version 3.22.0
3134 warns when the policy is not set and uses OLD behavior. Use the
3135 cmake_policy() command to set it to OLD or NEW explicitly.
3136 NOTE:
3138 The OLD behavior of a policy is deprecated by definition and may be
3139 removed in a future version of CMake.
3140 CMP0038
3142 Targets may not link directly to themselves.
3143 CMake 2.8.12 and lower allowed a build target to link to itself di‐
3145 rectly with a target_link_libraries() call. This is an indicator of a
3146 bug in user code.
3147 The OLD behavior for this policy is to ignore targets which list them‐
3149 selves in their own link implementation. The NEW behavior for this
3150 policy is to report an error if a target attempts to link to itself.
3151 This policy was introduced in CMake version 3.0. CMake version 3.22.0
3153 warns when the policy is not set and uses OLD behavior. Use the
3154 cmake_policy() command to set it to OLD or NEW explicitly.
3155 NOTE:
3157 The OLD behavior of a policy is deprecated by definition and may be
3158 removed in a future version of CMake.
3159 CMP0037
3161 Target names should not be reserved and should match a validity pat‐
3162 tern.
3163 CMake 2.8.12 and lower allowed creating targets using add_library(),
3165 add_executable() and add_custom_target() with unrestricted choice for
3166 the target name. Newer cmake features such as cmake-generator-expres‐
3167 sions(7) and some diagnostics expect target names to match a restricted
3168 pattern.
3169 Target names may contain upper and lower case letters, numbers, the un‐
3171 derscore character (_), dot(.), plus(+) and minus(-). As a special
3172 case, ALIAS and IMPORTED targets may contain two consecutive colons.
3173 Target names reserved by one or more CMake generators are not allowed.
3175 Among others these include all, clean, help, and install.
3176 Target names associated with optional features, such as test and pack‐
3178 age, may also be reserved. CMake 3.10 and below always reserve them.
3179 CMake 3.11 and above reserve them only when the corresponding feature
3180 is enabled (e.g. by including the CTest or CPack modules).
3181 The OLD behavior for this policy is to allow creating targets with re‐
3183 served names or which do not match the validity pattern. The NEW be‐
3184 havior for this policy is to report an error if an add_* command is
3185 used with an invalid target name.
3186 This policy was introduced in CMake version 3.0. CMake version 3.22.0
3188 warns when the policy is not set and uses OLD behavior. Use the
3189 cmake_policy() command to set it to OLD or NEW explicitly.
3190 NOTE:
3192 The OLD behavior of a policy is deprecated by definition and may be
3193 removed in a future version of CMake.
3194 CMP0036
3196 The build_name() command should not be called.
3197 This command was added in May 2001 to compute a name for the current
3199 operating system and compiler combination. The command has long been
3200 documented as discouraged and replaced by the CMAKE_SYSTEM and
3201 CMAKE_<LANG>_COMPILER variables.
3202 CMake >= 3.0 prefer that this command never be called. The OLD behav‐
3204 ior for this policy is to allow the command to be called. The NEW be‐
3205 havior for this policy is to issue a FATAL_ERROR when the command is
3206 called.
3207 This policy was introduced in CMake version 3.0. CMake version 3.22.0
3209 warns when the policy is not set and uses OLD behavior. Use the
3210 cmake_policy() command to set it to OLD or NEW explicitly.
3211 NOTE:
3213 The OLD behavior of a policy is deprecated by definition and may be
3214 removed in a future version of CMake.
3215 CMP0035
3217 The variable_requires() command should not be called.
3218 This command was introduced in November 2001 to perform some condi‐
3220 tional logic. It has long been replaced by the if() command.
3221 CMake >= 3.0 prefer that this command never be called. The OLD behav‐
3223 ior for this policy is to allow the command to be called. The NEW be‐
3224 havior for this policy is to issue a FATAL_ERROR when the command is
3225 called.
3226 This policy was introduced in CMake version 3.0. CMake version 3.22.0
3228 warns when the policy is not set and uses OLD behavior. Use the
3229 cmake_policy() command to set it to OLD or NEW explicitly.
3230 NOTE:
3232 The OLD behavior of a policy is deprecated by definition and may be
3233 removed in a future version of CMake.
3234 CMP0034
3236 The utility_source() command should not be called.
3237 This command was introduced in March 2001 to help build executables
3239 used to generate other files. This approach has long been replaced by
3240 add_executable() combined with add_custom_command().
3241 CMake >= 3.0 prefer that this command never be called. The OLD behav‐
3243 ior for this policy is to allow the command to be called. The NEW be‐
3244 havior for this policy is to issue a FATAL_ERROR when the command is
3245 called.
3246 This policy was introduced in CMake version 3.0. CMake version 3.22.0
3248 warns when the policy is not set and uses OLD behavior. Use the
3249 cmake_policy() command to set it to OLD or NEW explicitly.
3250 NOTE:
3252 The OLD behavior of a policy is deprecated by definition and may be
3253 removed in a future version of CMake.
3254 CMP0033
3256 The export_library_dependencies() command should not be called.
3257 This command was added in January 2003 to export <tgt>_LIB_DEPENDS in‐
3259 ternal CMake cache entries to a file for installation with a project.
3260 This was used at the time to allow transitive link dependencies to work
3261 for applications outside of the original build tree of a project. The
3262 functionality has been superseded by the export() and install(EXPORT)
3263 commands.
3264 CMake >= 3.0 prefer that this command never be called. The OLD behav‐
3266 ior for this policy is to allow the command to be called. The NEW be‐
3267 havior for this policy is to issue a FATAL_ERROR when the command is
3268 called.
3269 This policy was introduced in CMake version 3.0. CMake version 3.22.0
3271 warns when the policy is not set and uses OLD behavior. Use the
3272 cmake_policy() command to set it to OLD or NEW explicitly.
3273 NOTE:
3275 The OLD behavior of a policy is deprecated by definition and may be
3276 removed in a future version of CMake.
3277 CMP0032
3279 The output_required_files() command should not be called.
3280 This command was added in June 2001 to expose the then-current CMake
3282 implicit dependency scanner. CMake's real implicit dependency scanner
3283 has evolved since then but is not exposed through this command. The
3284 scanning capabilities of this command are very limited and this func‐
3285 tionality is better achieved through dedicated outside tools.
3286 CMake >= 3.0 prefer that this command never be called. The OLD behav‐
3288 ior for this policy is to allow the command to be called. The NEW be‐
3289 havior for this policy is to issue a FATAL_ERROR when the command is
3290 called.
3291 This policy was introduced in CMake version 3.0. CMake version 3.22.0
3293 warns when the policy is not set and uses OLD behavior. Use the
3294 cmake_policy() command to set it to OLD or NEW explicitly.
3295 NOTE:
3297 The OLD behavior of a policy is deprecated by definition and may be
3298 removed in a future version of CMake.
3299 CMP0031
3301 The load_command() command should not be called.
3302 This command was added in August 2002 to allow projects to add arbi‐
3304 trary commands implemented in C or C++. However, it does not work when
3305 the toolchain in use does not match the ABI of the CMake process. It
3306 has been mostly superseded by the macro() and function() commands.
3307 CMake >= 3.0 prefer that this command never be called. The OLD behav‐
3309 ior for this policy is to allow the command to be called. The NEW be‐
3310 havior for this policy is to issue a FATAL_ERROR when the command is
3311 called.
3312 This policy was introduced in CMake version 3.0. CMake version 3.22.0
3314 warns when the policy is not set and uses OLD behavior. Use the
3315 cmake_policy() command to set it to OLD or NEW explicitly.
3316 NOTE:
3318 The OLD behavior of a policy is deprecated by definition and may be
3319 removed in a future version of CMake.
3320 CMP0030
3322 The use_mangled_mesa() command should not be called.
3323 This command was created in September 2001 to support VTK before modern
3325 CMake language and custom command capabilities. VTK has not used it in
3326 years.
3327 CMake >= 3.0 prefer that this command never be called. The OLD behav‐
3329 ior for this policy is to allow the command to be called. The NEW be‐
3330 havior for this policy is to issue a FATAL_ERROR when the command is
3331 called.
3332 This policy was introduced in CMake version 3.0. CMake version 3.22.0
3334 warns when the policy is not set and uses OLD behavior. Use the
3335 cmake_policy() command to set it to OLD or NEW explicitly.
3336 NOTE:
3338 The OLD behavior of a policy is deprecated by definition and may be
3339 removed in a future version of CMake.
3340 CMP0029
3342 The subdir_depends() command should not be called.
3343 The implementation of this command has been empty since December 2001
3345 but was kept in CMake for compatibility for a long time.
3346 CMake >= 3.0 prefer that this command never be called. The OLD behav‐
3348 ior for this policy is to allow the command to be called. The NEW be‐
3349 havior for this policy is to issue a FATAL_ERROR when the command is
3350 called.
3351 This policy was introduced in CMake version 3.0. CMake version 3.22.0
3353 warns when the policy is not set and uses OLD behavior. Use the
3354 cmake_policy() command to set it to OLD or NEW explicitly.
3355 NOTE:
3357 The OLD behavior of a policy is deprecated by definition and may be
3358 removed in a future version of CMake.
3359 CMP0028
3361 Double colon in target name means ALIAS or IMPORTED target.
3362 CMake 2.8.12 and lower allowed the use of targets and files with double
3364 colons in target_link_libraries(), with some buildsystem generators.
3365 The use of double-colons is a common pattern used to namespace IMPORTED
3367 targets and ALIAS targets. When computing the link dependencies of a
3368 target, the name of each dependency could either be a target, or a file
3369 on disk. Previously, if a target was not found with a matching name,
3370 the name was considered to refer to a file on disk. This can lead to
3371 confusing error messages if there is a typo in what should be a target
3372 name.
3373 The OLD behavior for this policy is to search for targets, then files
3375 on disk, even if the search term contains double-colons. The NEW be‐
3376 havior for this policy is to issue a FATAL_ERROR if a link dependency
3377 contains double-colons but is not an IMPORTED target or an ALIAS tar‐
3378 get.
3379 This policy was introduced in CMake version 3.0. CMake version 3.22.0
3381 warns when the policy is not set and uses OLD behavior. Use the
3382 cmake_policy() command to set it to OLD or NEW explicitly.
3383 NOTE:
3385 The OLD behavior of a policy is deprecated by definition and may be
3386 removed in a future version of CMake.
3387 CMP0027
3389 Conditionally linked imported targets with missing include directories.
3390 CMake 2.8.11 introduced introduced the concept of INTERFACE_INCLUDE_DI‐
3392 RECTORIES, and a check at cmake time that the entries in the INTER‐
3393 FACE_INCLUDE_DIRECTORIES of an IMPORTED target actually exist. CMake
3394 2.8.11 also introduced generator expression support in the tar‐
3395 get_link_libraries() command. However, if an imported target is linked
3396 as a result of a generator expression evaluation, the entries in the
3397 INTERFACE_INCLUDE_DIRECTORIES of that target were not checked for exis‐
3398 tence as they should be.
3399 The OLD behavior of this policy is to report a warning if an entry in
3401 the INTERFACE_INCLUDE_DIRECTORIES of a generator-expression condition‐
3402 ally linked IMPORTED target does not exist.
3403 The NEW behavior of this policy is to report an error if an entry in
3405 the INTERFACE_INCLUDE_DIRECTORIES of a generator-expression condition‐
3406 ally linked IMPORTED target does not exist.
3407 This policy was introduced in CMake version 3.0. CMake version 3.22.0
3409 warns when the policy is not set and uses OLD behavior. Use the
3410 cmake_policy() command to set it to OLD or NEW explicitly.
3411 NOTE:
3413 The OLD behavior of a policy is deprecated by definition and may be
3414 removed in a future version of CMake.
3415 CMP0026
3417 Disallow use of the LOCATION property for build targets.
3418 CMake 2.8.12 and lower allowed reading the LOCATION target property
3420 (and configuration-specific variants) to determine the eventual loca‐
3421 tion of build targets. This relies on the assumption that all neces‐
3422 sary information is available at configure-time to determine the final
3423 location and filename of the target. However, this property is not
3424 fully determined until later at generate-time. At generate time, the
3425 $<TARGET_FILE> generator expression can be used to determine the even‐
3426 tual LOCATION of a target output.
3427 Code which reads the LOCATION target property can be ported to use the
3429 $<TARGET_FILE> generator expression together with the file(GENERATE)
3430 subcommand to generate a file containing the target location.
3431 The OLD behavior for this policy is to allow reading the LOCATION prop‐
3433 erties from build-targets. The NEW behavior for this policy is to not
3434 to allow reading the LOCATION properties from build-targets.
3435 This policy was introduced in CMake version 3.0. CMake version 3.22.0
3437 warns when the policy is not set and uses OLD behavior. Use the
3438 cmake_policy() command to set it to OLD or NEW explicitly.
3439 NOTE:
3441 The OLD behavior of a policy is deprecated by definition and may be
3442 removed in a future version of CMake.
3443 CMP0025
3445 Compiler id for Apple Clang is now AppleClang.
3446 CMake 3.0 and above recognize that Apple Clang is a different compiler
3448 than upstream Clang and that they have different version numbers.
3449 CMake now prefers to present this to projects by setting the
3450 CMAKE_<LANG>_COMPILER_ID variable to AppleClang instead of Clang. How‐
3451 ever, existing projects may assume the compiler id for Apple Clang is
3452 just Clang as it was in CMake versions prior to 3.0. Therefore this
3453 policy determines for Apple Clang which compiler id to report in the
3454 CMAKE_<LANG>_COMPILER_ID variable after language <LANG> is enabled by
3455 the project() or enable_language() command. The policy must be set
3456 prior to the invocation of either command.
3457 The OLD behavior for this policy is to use compiler id Clang. The NEW
3459 behavior for this policy is to use compiler id AppleClang.
3460 This policy was introduced in CMake version 3.0. Use the cmake_pol‐
3462 icy() command to set this policy to OLD or NEW explicitly. Unlike most
3463 policies, CMake version 3.22.0 does not warn by default when this pol‐
3464 icy is not set and simply uses OLD behavior. See documentation of the
3465 CMAKE_POLICY_WARNING_CMP0025 variable to control the warning.
3466 NOTE:
3468 The OLD behavior of a policy is deprecated by definition and may be
3469 removed in a future version of CMake.
3470 CMP0024
3472 Disallow include export result.
3473 CMake 2.8.12 and lower allowed use of the include() command with the
3475 result of the export() command. This relies on the assumption that the
3476 export() command has an immediate effect at configure-time during a
3477 cmake run. Certain properties of targets are not fully determined un‐
3478 til later at generate-time, such as the link language and complete list
3479 of link libraries. Future refactoring will change the effect of the
3480 export() command to be executed at generate-time. Use ALIAS targets
3481 instead in cases where the goal is to refer to targets by another name.
3482 The OLD behavior for this policy is to allow including the result of an
3484 export() command. The NEW behavior for this policy is not to allow in‐
3485 cluding the result of an export() command.
3486 This policy was introduced in CMake version 3.0. CMake version 3.22.0
3488 warns when the policy is not set and uses OLD behavior. Use the
3489 cmake_policy() command to set it to OLD or NEW explicitly.
3490 NOTE:
3492 The OLD behavior of a policy is deprecated by definition and may be
3493 removed in a future version of CMake.
3494
3496 CMP0023
3497 Plain and keyword target_link_libraries() signatures cannot be mixed.
3498 CMake 2.8.12 introduced the target_link_libraries() signature using the
3500 PUBLIC, PRIVATE, and INTERFACE keywords to generalize the LINK_PUBLIC
3501 and LINK_PRIVATE keywords introduced in CMake 2.8.7. Use of signatures
3502 with any of these keywords sets the link interface of a target explic‐
3503 itly, even if empty. This produces confusing behavior when used in
3504 combination with the historical behavior of the plain target_link_li‐
3505 braries() signature. For example, consider the code:
3506 target_link_libraries(mylib A)
3508 target_link_libraries(mylib PRIVATE B)
3509 After the first line the link interface has not been set explicitly so
3511 CMake would use the link implementation, A, as the link interface.
3512 However, the second line sets the link interface to empty. In order to
3513 avoid this subtle behavior CMake now prefers to disallow mixing the
3514 plain and keyword signatures of target_link_libraries() for a single
3515 target.
3516 The OLD behavior for this policy is to allow keyword and plain tar‐
3518 get_link_libraries() signatures to be mixed. The NEW behavior for this
3519 policy is to not to allow mixing of the keyword and plain signatures.
3520 This policy was introduced in CMake version 2.8.12. CMake version
3522 3.22.0 warns when the policy is not set and uses OLD behavior. Use the
3523 cmake_policy() command to set it to OLD or NEW explicitly.
3524 NOTE:
3526 The OLD behavior of a policy is deprecated by definition and may be
3527 removed in a future version of CMake.
3528 CMP0022
3530 INTERFACE_LINK_LIBRARIES defines the link interface.
3531 CMake 2.8.11 constructed the 'link interface' of a target from proper‐
3533 ties matching (IMPORTED_)?LINK_INTERFACE_LIBRARIES(_<CONFIG>)?. The
3534 modern way to specify config-sensitive content is to use generator ex‐
3535 pressions and the IMPORTED_ prefix makes uniform processing of the link
3536 interface with generator expressions impossible. The INTER‐
3537 FACE_LINK_LIBRARIES target property was introduced as a replacement in
3538 CMake 2.8.12. This new property is named consistently with the INTER‐
3539 FACE_COMPILE_DEFINITIONS, INTERFACE_INCLUDE_DIRECTORIES and INTER‐
3540 FACE_COMPILE_OPTIONS properties. For in-build targets, CMake will use
3541 the INTERFACE_LINK_LIBRARIES property as the source of the link inter‐
3542 face only if policy CMP0022 is NEW. When exporting a target which has
3543 this policy set to NEW, only the INTERFACE_LINK_LIBRARIES property will
3544 be processed and generated for the IMPORTED target by default. A new
3545 option to the install(EXPORT) and export commands allows export of the
3546 old-style properties for compatibility with downstream users of CMake
3547 versions older than 2.8.12. The target_link_libraries() command will
3548 no longer populate the properties matching LINK_INTERFACE_LI‐
3549 BRARIES(_<CONFIG>)? if this policy is NEW.
3550 Warning-free future-compatible code which works with CMake 2.8.7 on‐
3552 wards can be written by using the LINK_PRIVATE and LINK_PUBLIC keywords
3553 of target_link_libraries().
3554 The OLD behavior for this policy is to ignore the INTERFACE_LINK_LI‐
3556 BRARIES property for in-build targets. The NEW behavior for this pol‐
3557 icy is to use the INTERFACE_LINK_LIBRARIES property for in-build tar‐
3558 gets, and ignore the old properties matching (IMPORTED_)?LINK_INTER‐
3559 FACE_LIBRARIES(_<CONFIG>)?.
3560 This policy was introduced in CMake version 2.8.12. CMake version
3562 3.22.0 warns when the policy is not set and uses OLD behavior. Use the
3563 cmake_policy() command to set it to OLD or NEW explicitly.
3564 NOTE:
3566 The OLD behavior of a policy is deprecated by definition and may be
3567 removed in a future version of CMake.
3568 CMP0021
3570 Fatal error on relative paths in INCLUDE_DIRECTORIES target property.
3571 CMake 2.8.10.2 and lower allowed the INCLUDE_DIRECTORIES target prop‐
3573 erty to contain relative paths. The base path for such relative en‐
3574 tries is not well defined. CMake 2.8.12 issues a FATAL_ERROR if the
3575 INCLUDE_DIRECTORIES property contains a relative path.
3576 The OLD behavior for this policy is not to warn about relative paths in
3578 the INCLUDE_DIRECTORIES target property. The NEW behavior for this
3579 policy is to issue a FATAL_ERROR if INCLUDE_DIRECTORIES contains a rel‐
3580 ative path.
3581 This policy was introduced in CMake version 2.8.12. CMake version
3583 3.22.0 warns when the policy is not set and uses OLD behavior. Use the
3584 cmake_policy() command to set it to OLD or NEW explicitly.
3585 NOTE:
3587 The OLD behavior of a policy is deprecated by definition and may be
3588 removed in a future version of CMake.
3589 CMP0020
3591 Automatically link Qt executables to qtmain target on Windows.
3592 CMake 2.8.10 and lower required users of Qt to always specify a link
3594 dependency to the qtmain.lib static library manually on Windows. CMake
3595 2.8.11 gained the ability to evaluate generator expressions while de‐
3596 termining the link dependencies from IMPORTED targets. This allows
3597 CMake itself to automatically link executables which link to Qt to the
3598 qtmain.lib library when using IMPORTED Qt targets. For applications
3599 already linking to qtmain.lib, this should have little impact. For ap‐
3600 plications which supply their own alternative WinMain implementation
3601 and for applications which use the QAxServer library, this automatic
3602 linking will need to be disabled as per the documentation.
3603 The OLD behavior for this policy is not to link executables to qt‐
3605 main.lib automatically when they link to the QtCore IMPORTED target.
3606 The NEW behavior for this policy is to link executables to qtmain.lib
3607 automatically when they link to QtCore IMPORTED target.
3608 This policy was introduced in CMake version 2.8.11. CMake version
3610 3.22.0 warns when the policy is not set and uses OLD behavior. Use the
3611 cmake_policy() command to set it to OLD or NEW explicitly.
3612 NOTE:
3614 The OLD behavior of a policy is deprecated by definition and may be
3615 removed in a future version of CMake.
3616 CMP0019
3618 Do not re-expand variables in include and link information.
3619 CMake 2.8.10 and lower re-evaluated values given to the include_direc‐
3621 tories, link_directories, and link_libraries commands to expand any
3622 leftover variable references at the end of the configuration step.
3623 This was for strict compatibility with VERY early CMake versions be‐
3624 cause all variable references are now normally evaluated during CMake
3625 language processing. CMake 2.8.11 and higher prefer to skip the extra
3626 evaluation.
3627 The OLD behavior for this policy is to re-evaluate the values for
3629 strict compatibility. The NEW behavior for this policy is to leave the
3630 values untouched.
3631 This policy was introduced in CMake version 2.8.11. CMake version
3633 3.22.0 warns when the policy is not set and uses OLD behavior. Use the
3634 cmake_policy() command to set it to OLD or NEW explicitly.
3635 NOTE:
3637 The OLD behavior of a policy is deprecated by definition and may be
3638 removed in a future version of CMake.
3639 CMP0018
3641 Ignore CMAKE_SHARED_LIBRARY_<Lang>_FLAGS variable.
3642 CMake 2.8.8 and lower compiled sources in SHARED and MODULE libraries
3644 using the value of the undocumented CMAKE_SHARED_LIBRARY_<Lang>_FLAGS
3645 platform variable. The variable contained platform-specific flags
3646 needed to compile objects for shared libraries. Typically it included
3647 a flag such as -fPIC for position independent code but also included
3648 other flags needed on certain platforms. CMake 2.8.9 and higher prefer
3649 instead to use the POSITION_INDEPENDENT_CODE target property to deter‐
3650 mine what targets should be position independent, and new undocumented
3651 platform variables to select flags while ignoring CMAKE_SHARED_LI‐
3652 BRARY_<Lang>_FLAGS completely.
3653 The default for either approach produces identical compilation flags,
3655 but if a project modifies CMAKE_SHARED_LIBRARY_<Lang>_FLAGS from its
3656 original value this policy determines which approach to use.
3657 The OLD behavior for this policy is to ignore the POSITION_INDEPEN‐
3659 DENT_CODE property for all targets and use the modified value of
3660 CMAKE_SHARED_LIBRARY_<Lang>_FLAGS for SHARED and MODULE libraries.
3661 The NEW behavior for this policy is to ignore CMAKE_SHARED_LI‐
3663 BRARY_<Lang>_FLAGS whether it is modified or not and honor the POSI‐
3664 TION_INDEPENDENT_CODE target property.
3665 This policy was introduced in CMake version 2.8.9. CMake version
3667 3.22.0 warns when the policy is not set and uses OLD behavior. Use the
3668 cmake_policy() command to set it to OLD or NEW explicitly.
3669 NOTE:
3671 The OLD behavior of a policy is deprecated by definition and may be
3672 removed in a future version of CMake.
3673 CMP0017
3675 Prefer files from the CMake module directory when including from there.
3676 Starting with CMake 2.8.4, if a cmake-module shipped with CMake (i.e.
3678 located in the CMake module directory) calls include() or find_pack‐
3679 age(), the files located in the CMake module directory are preferred
3680 over the files in CMAKE_MODULE_PATH. This makes sure that the modules
3681 belonging to CMake always get those files included which they expect,
3682 and against which they were developed and tested. In all other cases,
3683 the files found in CMAKE_MODULE_PATH still take precedence over the
3684 ones in the CMake module directory. The OLD behavior is to always pre‐
3685 fer files from CMAKE_MODULE_PATH over files from the CMake modules di‐
3686 rectory.
3687 This policy was introduced in CMake version 2.8.4. CMake version
3689 3.22.0 warns when the policy is not set and uses OLD behavior. Use the
3690 cmake_policy() command to set it to OLD or NEW explicitly.
3691 NOTE:
3693 The OLD behavior of a policy is deprecated by definition and may be
3694 removed in a future version of CMake.
3695 CMP0016
3697 target_link_libraries() reports error if its only argument is not a
3698 target.
3699 In CMake 2.8.2 and lower the target_link_libraries() command silently
3701 ignored if it was called with only one argument, and this argument
3702 wasn't a valid target. In CMake 2.8.3 and above it reports an error in
3703 this case.
3704 This policy was introduced in CMake version 2.8.3. CMake version
3706 3.22.0 warns when the policy is not set and uses OLD behavior. Use the
3707 cmake_policy() command to set it to OLD or NEW explicitly.
3708 NOTE:
3710 The OLD behavior of a policy is deprecated by definition and may be
3711 removed in a future version of CMake.
3712 CMP0015
3714 link_directories() treats paths relative to the source dir.
3715 In CMake 2.8.0 and lower the link_directories() command passed relative
3717 paths unchanged to the linker. In CMake 2.8.1 and above the link_di‐
3718 rectories() command prefers to interpret relative paths with respect to
3719 CMAKE_CURRENT_SOURCE_DIR, which is consistent with include_directo‐
3720 ries() and other commands. The OLD behavior for this policy is to use
3721 relative paths verbatim in the linker command. The NEW behavior for
3722 this policy is to convert relative paths to absolute paths by appending
3723 the relative path to CMAKE_CURRENT_SOURCE_DIR.
3724 This policy was introduced in CMake version 2.8.1. CMake version
3726 3.22.0 warns when the policy is not set and uses OLD behavior. Use the
3727 cmake_policy() command to set it to OLD or NEW explicitly.
3728 NOTE:
3730 The OLD behavior of a policy is deprecated by definition and may be
3731 removed in a future version of CMake.
3732 CMP0014
3734 Input directories must have CMakeLists.txt.
3735 CMake versions before 2.8 silently ignored missing CMakeLists.txt files
3737 in directories referenced by add_subdirectory() or subdirs(), treating
3738 them as if present but empty. In CMake 2.8.0 and above this cmake_pol‐
3739 icy() determines whether or not the case is an error. The OLD behavior
3740 for this policy is to silently ignore the problem. The NEW behavior
3741 for this policy is to report an error.
3742 This policy was introduced in CMake version 2.8.0. CMake version
3744 3.22.0 warns when the policy is not set and uses OLD behavior. Use the
3745 cmake_policy() command to set it to OLD or NEW explicitly.
3746 NOTE:
3748 The OLD behavior of a policy is deprecated by definition and may be
3749 removed in a future version of CMake.
3750 CMP0013
3752 Duplicate binary directories are not allowed.
3753 CMake 2.6.3 and below silently permitted add_subdirectory() calls to
3755 create the same binary directory multiple times. During build system
3756 generation files would be written and then overwritten in the build
3757 tree and could lead to strange behavior. CMake 2.6.4 and above explic‐
3758 itly detect duplicate binary directories. CMake 2.6.4 always considers
3759 this case an error. In CMake 2.8.0 and above this policy determines
3760 whether or not the case is an error. The OLD behavior for this policy
3761 is to allow duplicate binary directories. The NEW behavior for this
3762 policy is to disallow duplicate binary directories with an error.
3763 This policy was introduced in CMake version 2.8.0. CMake version
3765 3.22.0 warns when the policy is not set and uses OLD behavior. Use the
3766 cmake_policy() command to set it to OLD or NEW explicitly.
3767 NOTE:
3769 The OLD behavior of a policy is deprecated by definition and may be
3770 removed in a future version of CMake.
3771 CMP0012
3773 if() recognizes numbers and boolean constants.
3774 In CMake versions 2.6.4 and lower the if() command implicitly derefer‐
3776 enced arguments corresponding to variables, even those named like num‐
3777 bers or boolean constants, except for 0 and 1. Numbers and boolean
3778 constants such as true, false, yes, no, on, off, y, n, notfound, ignore
3779 (all case insensitive) were recognized in some cases but not all. For
3780 example, the code if(TRUE) might have evaluated as false. Numbers such
3781 as 2 were recognized only in boolean expressions like if(NOT 2) (lead‐
3782 ing to false) but not as a single-argument like if(2) (also leading to
3783 false). Later versions of CMake prefer to treat numbers and boolean
3784 constants literally, so they should not be used as variable names.
3785 The OLD behavior for this policy is to implicitly dereference variables
3787 named like numbers and boolean constants. The NEW behavior for this
3788 policy is to recognize numbers and boolean constants without derefer‐
3789 encing variables with such names.
3790 This policy was introduced in CMake version 2.8.0. CMake version
3792 3.22.0 warns when the policy is not set and uses OLD behavior. Use the
3793 cmake_policy() command to set it to OLD or NEW explicitly.
3794 NOTE:
3796 The OLD behavior of a policy is deprecated by definition and may be
3797 removed in a future version of CMake.
3798
3800 CMP0011
3801 Included scripts do automatic cmake_policy() PUSH and POP.
3802 In CMake 2.6.2 and below, CMake Policy settings in scripts loaded by
3804 the include() and find_package() commands would affect the includer.
3805 Explicit invocations of cmake_policy(PUSH) and cmake_policy(POP) were
3806 required to isolate policy changes and protect the includer. While
3807 some scripts intend to affect the policies of their includer, most do
3808 not. In CMake 2.6.3 and above, include() and find_package() by default
3809 PUSH and POP an entry on the policy stack around an included script,
3810 but provide a NO_POLICY_SCOPE option to disable it. This policy deter‐
3811 mines whether or not to imply NO_POLICY_SCOPE for compatibility. The
3812 OLD behavior for this policy is to imply NO_POLICY_SCOPE for include()
3813 and find_package() commands. The NEW behavior for this policy is to
3814 allow the commands to do their default cmake_policy PUSH and POP.
3815 This policy was introduced in CMake version 2.6.3. CMake version
3817 3.22.0 warns when the policy is not set and uses OLD behavior. Use the
3818 cmake_policy() command to set it to OLD or NEW explicitly.
3819 NOTE:
3821 The OLD behavior of a policy is deprecated by definition and may be
3822 removed in a future version of CMake.
3823 CMP0010
3825 Bad variable reference syntax is an error.
3826 In CMake 2.6.2 and below, incorrect variable reference syntax such as a
3828 missing close-brace (${FOO) was reported but did not stop processing of
3829 CMake code. This policy determines whether a bad variable reference is
3830 an error. The OLD behavior for this policy is to warn about the error,
3831 leave the string untouched, and continue. The NEW behavior for this
3832 policy is to report an error.
3833 If CMP0053 is set to NEW, this policy has no effect and is treated as
3835 always being NEW.
3836 This policy was introduced in CMake version 2.6.3. CMake version
3838 3.22.0 warns when the policy is not set and uses OLD behavior. Use the
3839 cmake_policy() command to set it to OLD or NEW explicitly.
3840 NOTE:
3842 The OLD behavior of a policy is deprecated by definition and may be
3843 removed in a future version of CMake.
3844 CMP0009
3846 FILE GLOB_RECURSE calls should not follow symlinks by default.
3847 In CMake 2.6.1 and below, file(GLOB_RECURSE) calls would follow through
3849 symlinks, sometimes coming up with unexpectedly large result sets be‐
3850 cause of symlinks to top level directories that contain hundreds of
3851 thousands of files.
3852 This policy determines whether or not to follow symlinks encountered
3854 during a file(GLOB_RECURSE) call. The OLD behavior for this policy is
3855 to follow the symlinks. The NEW behavior for this policy is not to
3856 follow the symlinks by default, but only if FOLLOW_SYMLINKS is given as
3857 an additional argument to the FILE command.
3858 This policy was introduced in CMake version 2.6.2. CMake version
3860 3.22.0 warns when the policy is not set and uses OLD behavior. Use the
3861 cmake_policy() command to set it to OLD or NEW explicitly.
3862 NOTE:
3864 The OLD behavior of a policy is deprecated by definition and may be
3865 removed in a future version of CMake.
3866 CMP0008
3868 Libraries linked by full-path must have a valid library file name.
3869 In CMake 2.4 and below it is possible to write code like
3871 target_link_libraries(myexe /full/path/to/somelib)
3873 where somelib is supposed to be a valid library file name such as lib‐
3875 somelib.a or somelib.lib. For Makefile generators this produces an er‐
3876 ror at build time because the dependency on the full path cannot be
3877 found. For Visual Studio Generators IDE and Xcode generators this used
3878 to work by accident because CMake would always split off the library
3879 directory and ask the linker to search for the library by name
3880 (-lsomelib or somelib.lib). Despite the failure with Makefiles, some
3881 projects have code like this and build only with Visual Studio and/or
3882 Xcode. This version of CMake prefers to pass the full path directly to
3883 the native build tool, which will fail in this case because it does not
3884 name a valid library file.
3885 This policy determines what to do with full paths that do not appear to
3887 name a valid library file. The OLD behavior for this policy is to
3888 split the library name from the path and ask the linker to search for
3889 it. The NEW behavior for this policy is to trust the given path and
3890 pass it directly to the native build tool unchanged.
3891 This policy was introduced in CMake version 2.6.1. CMake version
3893 3.22.0 warns when the policy is not set and uses OLD behavior. Use the
3894 cmake_policy() command to set it to OLD or NEW explicitly.
3895 NOTE:
3897 The OLD behavior of a policy is deprecated by definition and may be
3898 removed in a future version of CMake.
3899 CMP0007
3901 list command no longer ignores empty elements.
3902 This policy determines whether the list command will ignore empty ele‐
3904 ments in the list. CMake 2.4 and below list commands ignored all empty
3905 elements in the list. For example, a;b;;c would have length 3 and not
3906 4. The OLD behavior for this policy is to ignore empty list elements.
3907 The NEW behavior for this policy is to correctly count empty elements
3908 in a list.
3909 This policy was introduced in CMake version 2.6.0. CMake version
3911 3.22.0 warns when the policy is not set and uses OLD behavior. Use the
3912 cmake_policy() command to set it to OLD or NEW explicitly.
3913 NOTE:
3915 The OLD behavior of a policy is deprecated by definition and may be
3916 removed in a future version of CMake.
3917 CMP0006
3919 Installing MACOSX_BUNDLE targets requires a BUNDLE DESTINATION.
3920 This policy determines whether the install(TARGETS) command must be
3922 given a BUNDLE DESTINATION when asked to install a target with the MA‐
3923 COSX_BUNDLE property set. CMake 2.4 and below did not distinguish ap‐
3924 plication bundles from normal executables when installing targets.
3925 CMake 2.6 provides a BUNDLE option to the install(TARGETS) command that
3926 specifies rules specific to application bundles on the Mac. Projects
3927 should use this option when installing a target with the MACOSX_BUNDLE
3928 property set.
3929 The OLD behavior for this policy is to fall back to the RUNTIME DESTI‐
3931 NATION if a BUNDLE DESTINATION is not given. The NEW behavior for this
3932 policy is to produce an error if a bundle target is installed without a
3933 BUNDLE DESTINATION.
3934 This policy was introduced in CMake version 2.6.0. CMake version
3936 3.22.0 warns when the policy is not set and uses OLD behavior. Use the
3937 cmake_policy() command to set it to OLD or NEW explicitly.
3938 NOTE:
3940 The OLD behavior of a policy is deprecated by definition and may be
3941 removed in a future version of CMake.
3942 CMP0005
3944 Preprocessor definition values are now escaped automatically.
3945 This policy determines whether or not CMake should generate escaped
3947 preprocessor definition values added via add_definitions. CMake ver‐
3948 sions 2.4 and below assumed that only trivial values would be given for
3949 macros in add_definitions calls. It did not attempt to escape
3950 non-trivial values such as string literals in generated build rules.
3951 CMake versions 2.6 and above support escaping of most values, but can‐
3952 not assume the user has not added escapes already in an attempt to work
3953 around limitations in earlier versions.
3954 The OLD behavior for this policy is to place definition values given to
3956 add_definitions directly in the generated build rules without attempt‐
3957 ing to escape anything. The NEW behavior for this policy is to gener‐
3958 ate correct escapes for all native build tools automatically. See doc‐
3959 umentation of the COMPILE_DEFINITIONS target property for limitations
3960 of the escaping implementation.
3961 This policy was introduced in CMake version 2.6.0. CMake version
3963 3.22.0 warns when the policy is not set and uses OLD behavior. Use the
3964 cmake_policy() command to set it to OLD or NEW explicitly.
3965 NOTE:
3967 The OLD behavior of a policy is deprecated by definition and may be
3968 removed in a future version of CMake.
3969 CMP0004
3971 Libraries linked may not have leading or trailing whitespace.
3972 CMake versions 2.4 and below silently removed leading and trailing
3974 whitespace from libraries linked with code like
3975 target_link_libraries(myexe " A ")
3977 This could lead to subtle errors in user projects.
3979 The OLD behavior for this policy is to silently remove leading and
3981 trailing whitespace. The NEW behavior for this policy is to diagnose
3982 the existence of such whitespace as an error. The setting for this
3983 policy used when checking the library names is that in effect when the
3984 target is created by an add_executable() or add_library() command.
3985 This policy was introduced in CMake version 2.6.0. CMake version
3987 3.22.0 warns when the policy is not set and uses OLD behavior. Use the
3988 cmake_policy() command to set it to OLD or NEW explicitly.
3989 NOTE:
3991 The OLD behavior of a policy is deprecated by definition and may be
3992 removed in a future version of CMake.
3993 CMP0003
3995 Libraries linked via full path no longer produce linker search paths.
3996 This policy affects how libraries whose full paths are NOT known are
3998 found at link time, but was created due to a change in how CMake deals
3999 with libraries whose full paths are known. Consider the code
4000 target_link_libraries(myexe /path/to/libA.so)
4002 CMake 2.4 and below implemented linking to libraries whose full paths
4004 are known by splitting them on the link line into separate components
4005 consisting of the linker search path and the library name. The example
4006 code might have produced something like
4007 ... -L/path/to -lA ...
4009 in order to link to library A. An analysis was performed to order mul‐
4011 tiple link directories such that the linker would find library A in the
4012 desired location, but there are cases in which this does not work.
4013 CMake versions 2.6 and above use the more reliable approach of passing
4014 the full path to libraries directly to the linker in most cases. The
4015 example code now produces something like
4016 ... /path/to/libA.so ....
4018 Unfortunately this change can break code like
4020 target_link_libraries(myexe /path/to/libA.so B)
4022 where B is meant to find /path/to/libB.so. This code is wrong because
4024 the user is asking the linker to find library B but has not provided a
4025 linker search path (which may be added with the link_directories com‐
4026 mand). However, with the old linking implementation the code would
4027 work accidentally because the linker search path added for library A
4028 allowed library B to be found.
4029 In order to support projects depending on linker search paths added by
4031 linking to libraries with known full paths, the OLD behavior for this
4032 policy will add the linker search paths even though they are not needed
4033 for their own libraries. When this policy is set to OLD, CMake will
4034 produce a link line such as
4035 ... -L/path/to /path/to/libA.so -lB ...
4037 which will allow library B to be found as it was previously. When this
4039 policy is set to NEW, CMake will produce a link line such as
4040 ... /path/to/libA.so -lB ...
4042 which more accurately matches what the project specified.
4044 The setting for this policy used when generating the link line is that
4046 in effect when the target is created by an add_executable or add_li‐
4047 brary command. For the example described above, the code
4048 cmake_policy(SET CMP0003 OLD) # or cmake_policy(VERSION 2.4)
4050 add_executable(myexe myexe.c)
4051 target_link_libraries(myexe /path/to/libA.so B)
4052 will work and suppress the warning for this policy. It may also be up‐
4054 dated to work with the corrected linking approach:
4055 cmake_policy(SET CMP0003 NEW) # or cmake_policy(VERSION 2.6)
4057 link_directories(/path/to) # needed to find library B
4058 add_executable(myexe myexe.c)
4059 target_link_libraries(myexe /path/to/libA.so B)
4060 Even better, library B may be specified with a full path:
4062 add_executable(myexe myexe.c)
4064 target_link_libraries(myexe /path/to/libA.so /path/to/libB.so)
4065 When all items on the link line have known paths CMake does not check
4067 this policy so it has no effect.
4068 Note that the warning for this policy will be issued for at most one
4070 target. This avoids flooding users with messages for every target when
4071 setting the policy once will probably fix all targets.
4072 This policy was introduced in CMake version 2.6.0. CMake version
4074 3.22.0 warns when the policy is not set and uses OLD behavior. Use the
4075 cmake_policy() command to set it to OLD or NEW explicitly.
4076 NOTE:
4078 The OLD behavior of a policy is deprecated by definition and may be
4079 removed in a future version of CMake.
4080 CMP0002
4082 Logical target names must be globally unique.
4083 Targets names created with add_executable(), add_library(), or add_cus‐
4085 tom_target() are logical build target names. Logical target names must
4086 be globally unique because:
4087 - Unique names may be referenced unambiguously both in CMake
4089 code and on make tool command lines.
4090 - Logical names are used by Xcode and VS IDE generators
4091 to produce meaningful project names for the targets.
4092 The logical name of executable and library targets does not have to
4094 correspond to the physical file names built. Consider using the OUT‐
4095 PUT_NAME target property to create two targets with the same physical
4096 name while keeping logical names distinct. Custom targets must simply
4097 have globally unique names (unless one uses the global property AL‐
4098 LOW_DUPLICATE_CUSTOM_TARGETS with a Makefiles generator).
4099 This policy was introduced in CMake version 2.6.0. CMake version
4101 3.22.0 warns when the policy is not set and uses OLD behavior. Use the
4102 cmake_policy() command to set it to OLD or NEW explicitly.
4103 NOTE:
4105 The OLD behavior of a policy is deprecated by definition and may be
4106 removed in a future version of CMake.
4107 CMP0001
4109 CMAKE_BACKWARDS_COMPATIBILITY should no longer be used.
4110 The behavior is to check CMAKE_BACKWARDS_COMPATIBILITY and present it
4112 to the user. The NEW behavior is to ignore CMAKE_BACKWARDS_COMPATIBIL‐
4113 ITY completely.
4114 In CMake 2.4 and below the variable CMAKE_BACKWARDS_COMPATIBILITY was
4116 used to request compatibility with earlier versions of CMake. In CMake
4117 2.6 and above all compatibility issues are handled by policies and the
4118 cmake_policy() command. However, CMake must still check CMAKE_BACK‐
4119 WARDS_COMPATIBILITY for projects written for CMake 2.4 and below.
4120 This policy was introduced in CMake version 2.6.0. CMake version
4122 3.22.0 warns when the policy is not set and uses OLD behavior. Use the
4123 cmake_policy() command to set it to OLD or NEW explicitly.
4124 NOTE:
4126 The OLD behavior of a policy is deprecated by definition and may be
4127 removed in a future version of CMake.
4128 CMP0000
4130 A minimum required CMake version must be specified.
4131 CMake requires that projects specify the version of CMake to which they
4133 have been written. This policy has been put in place so users trying
4134 to build the project may be told when they need to update their CMake.
4135 Specifying a version also helps the project build with CMake versions
4136 newer than that specified. Use the cmake_minimum_required() command at
4137 the top of your main CMakeLists.txt file:
4138 cmake_minimum_required(VERSION <major>.<minor>)
4140 where <major>.<minor> is the version of CMake you want to support (such
4142 as 3.14). The command will ensure that at least the given version of
4143 CMake is running and help newer versions be compatible with the
4144 project. See documentation of cmake_minimum_required() for details.
4145 Note that the command invocation must appear in the CMakeLists.txt file
4147 itself; a call in an included file is not sufficient. However, the
4148 cmake_policy() command may be called to set policy CMP0000 to OLD or
4149 NEW behavior explicitly. The OLD behavior is to silently ignore the
4150 missing invocation. The NEW behavior is to issue an error instead of a
4151 warning. An included file may set CMP0000 explicitly to affect how
4152 this policy is enforced for the main CMakeLists.txt file.
4153 This policy was introduced in CMake version 2.6.0.
4155 NOTE:
4157 The OLD behavior of a policy is deprecated by definition and may be
4158 removed in a future version of CMake.
4159
4161 2000-2021 Kitware, Inc. and Contributors
41623.22.0 Dec 02, 2021 CMAKE-POLICIES(7)