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.2 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.2
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 within a project. Use
180 the CMAKE_POLICY_DEFAULT_CMP0126 variable to set the policy for a
181 third-party project in a subdirectory without modifying it. Unlike
182 many policies, CMake version 3.22.2 does not warn when the policy is
183 not set and simply uses OLD behavior. See documentation of the
184 CMAKE_POLICY_WARNING_CMP0126 variable to control the warning.
185 NOTE:
187 The OLD behavior of a policy is deprecated by definition and may be
188 removed in a future version of CMake.
189 CMP0125
191 New in version 3.21.
192 The find_file(), find_path(), find_library() and find_program() com‐
195 mands cache their result in the variable specified by their first argu‐
196 ment. Prior to CMake 3.21, if a cache variable of that name already
197 existed before the call but the cache variable had no type, any
198 non-cache variable of the same name would be discarded and the cache
199 variable was always used (see also CMP0126 for a different but similar
200 behavior). This contradicts the convention that a non-cache variable
201 should take precedence over a cache variable of the same name. Such a
202 situation can arise if a user sets a cache variable on the command line
203 without specifying a type, such as cmake -DMYVAR=blah ... instead of
204 cmake -DMYVAR:FILEPATH=blah.
205 Related to the above, if a cache variable of the specified name already
207 exists and it does have a type, the various find_...() commands would
208 return that value unchanged. In particular, if it contained a relative
209 path, it would not be converted to an absolute path in this situation.
210 When policy CMP0125 is set to OLD or is unset, the behavior is as de‐
212 scribed above. When it is set to NEW, the behavior is as follows:
213 • If a non-cache variable of the specified name exists when the
215 find_...() command is called, its value will be used regardless of
216 whether a cache variable of the same name already exists or not. A
217 cache variable will not be created in this case if no such cache
218 variable existed before. If a cache variable of the specified name
219 did already exist, the cache will be updated to match the non-cache
220 variable.
221 • The various find...() commands will always provide an absolute path
223 in the result variable, except where a relative path provided by a
224 cache or non-cache variable cannot be resolved to an existing path.
225 This policy was introduced in CMake version 3.21. Use the cmake_pol‐
227 icy() command to set it to OLD or NEW explicitly. Unlike many poli‐
228 cies, CMake version 3.22.2 does not warn when the policy is not set and
229 simply uses OLD behavior.
230 NOTE:
232 The OLD behavior of a policy is deprecated by definition and may be
233 removed in a future version of CMake.
234 CMP0124
236 New in version 3.21.
237 When this policy is set to NEW, the scope of loop variables defined by
240 the foreach() command is restricted to the loop only. They will be un‐
241 set at the end of the loop.
242 The OLD behavior for this policy still clears the loop variables at the
244 end of the loop, but does not unset them. This leaves them as defined,
245 but empty.
246 This policy was introduced in CMake version 3.21. Use the cmake_pol‐
248 icy() command to set it to OLD or NEW explicitly. Unlike many poli‐
249 cies, CMake version 3.22.2 does not warn when the policy is not set and
250 simply uses OLD behavior.
251 NOTE:
253 The OLD behavior of a policy is deprecated by definition and may be
254 removed in a future version of CMake.
255 CMP0123
257 New in version 3.21.
258 ARMClang cpu/arch compile and link flags must be set explicitly.
261 CMake 3.20 and lower automatically maps the CMAKE_SYSTEM_PROCESSOR
263 variable and an undocumented CMAKE_SYSTEM_ARCH to compile and link op‐
264 tions for ARMClang. For example, the -mcpu=cortex-m33 flag is added
265 when CMAKE_SYSTEM_PROCESSOR equals cortex-m33. CMake requires projects
266 to set either variable or it raises a fatal error. However, the
267 project may need to additionally specify CPU features using e.g.
268 -mcpu=cortex-m33+nodsp, conflicting with the -mcpu=cortex-m33 added by
269 CMake. This results in either link errors or unusable binaries.
270 CMake 3.21 and above prefer instead to not add any cpu/arch compile and
272 link flags automatically. Instead, projects must specify them explic‐
273 itly. This policy provides compatibility for projects that have not
274 been updated.
275 The OLD behavior of this policy requires projects that use ARMClang to
277 set either CMAKE_SYSTEM_PROCESSOR or CMAKE_SYSTEM_ARCH and it automati‐
278 cally adds a compile option -mcpu= or -march= and a link option --cpu=
279 based on those variables. The NEW behavior does not add compile or
280 link options, and projects are responsible for setting correct options.
281 This policy was introduced in CMake version 3.21. CMake version 3.22.2
283 warns when the policy is not set and uses OLD behavior. Use the
284 cmake_policy() command to set it to OLD or NEW explicitly.
285 NOTE:
287 The OLD behavior of a policy is deprecated by definition and may be
288 removed in a future version of CMake.
289 CMP0122
291 New in version 3.21.
292 UseSWIG use library name conventions for CSharp language.
295 Starting with CMake 3.21, UseSWIG generates now a library using default
297 naming conventions. This policy provides compatibility with projects
298 that expect the legacy behavior.
299 This policy was introduced in CMake version 3.21. CMake version 3.22.2
301 warns when the policy is not set and uses OLD behavior. Use the
302 cmake_policy() command to set it to OLD or NEW explicitly.
303 NOTE:
305 The OLD behavior of a policy is deprecated by definition and may be
306 removed in a future version of CMake.
307 CMP0121
309 New in version 3.21.
310 The list() command now detects invalid indices.
313 Prior to CMake version 3.21, the list() command's GET, INSERT, SUBLIST,
315 and REMOVE_AT subcommands did not detect invalid index arguments.
316 The OLD behavior of this policy is for invalid indices to be treated as
318 their integer value (if any) at the start of the string. For example,
319 2good4you is a 2 and not_an_integer is a 0. The NEW behavior is for in‐
320 valid indices to trigger an error.
321 This policy was introduced in CMake version 3.21. CMake version 3.22.2
323 warns when the policy is not set and uses OLD behavior. Use the
324 cmake_policy() command to set it to OLD or NEW explicitly.
325 NOTE:
327 The OLD behavior of a policy is deprecated by definition and may be
328 removed in a future version of CMake.
329
331 CMP0120
332 New in version 3.20.
333 The WriteCompilerDetectionHeader module is removed.
336 CMake versions 3.1 through 3.19 provide this module to generate a C++
338 compatibility layer by re-using information from CMake's table of pre‐
339 processor checks for cmake-compile-features(7). However:
340 • Those granular features have been superseded by meta-features for Re‐
342 quiring Language Standards such as cxx_std_11. Therefore no new
343 granular feature checks will be added and projects will need to use
344 other means to conditionally use new C++ features.
345 • The module exposes some of CMake's implementation details directly to
347 C++ translation units.
348 • The module's approach effectively provides a header file with CMake,
350 thus tying the version of the header to the version of CMake. Many
351 projects found that the WriteCompilerDetectionHeader was best used by
352 manually generating its header locally with a recent version of CMake
353 and then bundling it with the project source so that it could be used
354 with older CMake versions.
355 For reasons including the above, CMake 3.20 and above prefer to not
357 provide the WriteCompilerDetectionHeader module. This policy provides
358 compatibility for projects that have not been ported away from it.
359 Projects using the module should be updated to stop using it. Alterna‐
360 tives include:
361 • Bundle a copy of the generated header in the project's source.
363 • Use a third-party alternative, such as the CC0-licensed Hedley.
365 • Drop support for compilers too old to provide the features natively.
367 The OLD behavior of this policy is for inclusion of the deprecated
369 WriteCompilerDetectionHeader module to work. The NEW behavior is for
370 inclusion of the module to fail as if it does not exist.
371 This policy was introduced in CMake version 3.20. CMake version 3.22.2
373 warns when the policy is not set and uses OLD behavior. Use the
374 cmake_policy() command to set it to OLD or NEW explicitly.
375 NOTE:
377 The OLD behavior of a policy is deprecated by definition and may be
378 removed in a future version of CMake.
379 CMP0119
381 New in version 3.20.
382 LANGUAGE source file property explicitly compiles as specified lan‐
385 guage.
386 The LANGUAGE source file property is documented to mean that the source
388 file is written in the specified language. In CMake 3.19 and below,
389 setting this property causes CMake to compile the source file using the
390 compiler for the specified language. However, it only passes an ex‐
391 plicit flag to tell the compiler to treat the source as the specified
392 language for MSVC-like, XL, and Embarcadero compilers for the CXX lan‐
393 guage. CMake 3.20 and above prefer to also explicitly tell the com‐
394 piler to use the specified language using a flag such as -x c on all
395 compilers for which such flags are known.
396 This policy provides compatibility for projects that have not been up‐
398 dated to expect this behavior. For example, some projects were setting
399 the LANGUAGE property to C on assembly-language .S source files in or‐
400 der to compile them using the C compiler. Such projects should be up‐
401 dated to use enable_language(ASM), for which CMake will often choose
402 the C compiler as the assembler on relevant platforms anyway.
403 The OLD behavior for this policy is to interpret the LANGUAGE <LANG>
405 property using its undocumented meaning to "use the <LANG> compiler".
406 The NEW behavior for this policy is to interpret the LANGUAGE <LANG>
407 property using its documented meaning to "compile as a <LANG> source".
408 This policy was introduced in CMake version 3.20. Use the cmake_pol‐
410 icy() command to set it to OLD or NEW explicitly. Unlike many poli‐
411 cies, CMake version 3.22.2 does not warn when this policy is not set
412 and simply uses OLD behavior.
413 NOTE:
415 The OLD behavior of a policy is deprecated by definition and may be
416 removed in a future version of CMake.
417 CMP0118
419 New in version 3.20.
420 The GENERATED source file property is now visible in all directories.
423 Whether or not a source file is generated is an all-or-nothing global
425 property of the source. Consequently, the associated GENERATED prop‐
426 erty is now visible from any directory scope, not only from the scope
427 for which it was set.
428 Additionally, the GENERATED property may now be set only to boolean
430 values, and may not be turned off once turned on.
431 The OLD behavior of this policy is to only allow GENERATED to be visi‐
433 ble from the directory scope for which it was set. The NEW behavior on
434 the other hand allows it to be visible from any scope.
435 This policy was introduced in CMake version 3.20. Use the cmake_pol‐
437 icy() command to set it to OLD or NEW explicitly. Unlike many poli‐
438 cies, CMake version 3.22.2 does not warn when this policy is not set
439 and simply uses OLD behavior with regard to visibility of the GENERATED
440 property. However, CMake does warn about setting the GENERATED prop‐
441 erty to a non-boolean value.
442 CMP0117
444 New in version 3.20.
445 MSVC RTTI flag /GR is not added to CMAKE_CXX_FLAGS by default.
448 When using MSVC-like compilers in CMake 3.19 and below, the RTTI flag
450 /GR is added to CMAKE_CXX_FLAGS by default. This behavior is left from
451 support for MSVC versions from Visual Studio 2003 and below that did
452 not enable RTTI by default. It is no longer necessary. Furthermore,
453 it is problematic for projects that want to change to /GR- programmati‐
454 cally. In particular, it requires string editing of the
455 CMAKE_CXX_FLAGS variable with knowledge of the CMake builtin default so
456 it can be replaced.
457 CMake 3.20 and above prefer to leave out /GR from the value of
459 CMAKE_CXX_FLAGS by default.
460 This policy provides compatibility with projects that have not been up‐
462 dated to expect the lack of the /GR flag. The policy setting takes ef‐
463 fect as of the first project() or enable_language() command that ini‐
464 tializes CMAKE_CXX_FLAGS.
465 NOTE:
467 Once the policy has taken effect at the top of a project for a given
468 language, that choice must be used throughout the tree for that lan‐
469 guage. In projects that have nested projects in subdirectories, be
470 sure to convert everything together.
471 The OLD behavior for this policy is to place the MSVC /GR flag in the
473 default CMAKE_CXX_FLAGS cache entry. The NEW behavior for this policy
474 is to not place the MSVC /GR flag in the default cache entry.
475 This policy was introduced in CMake version 3.20. Use the cmake_pol‐
477 icy() command to set it to OLD or NEW explicitly. Unlike many poli‐
478 cies, CMake version 3.22.2 does not warn when this policy is not set
479 and simply uses OLD behavior.
480 NOTE:
482 The OLD behavior of a policy is deprecated by definition and may be
483 removed in a future version of CMake.
484 CMP0116
486 New in version 3.20.
487 Ninja generators transform DEPFILE s from add_custom_command().
490 In CMake 3.19 and below, files given to the DEPFILE argument of
492 add_custom_command() were passed directly to Ninja's depfile variable
493 without any path resolution. This meant that if add_custom_command()
494 was called from a subdirectory (created by add_subdirectory()), the
495 DEPFILE argument would have to be either an absolute path or a path
496 relative to CMAKE_BINARY_DIR, rather than CMAKE_CURRENT_BINARY_DIR. In
497 addition, no transformation was done on the file listed in DEPFILE,
498 which meant that the paths within the DEPFILE had the same restric‐
499 tions.
500 Starting with CMake 3.20, the DEPFILE argument is relative to
502 CMAKE_CURRENT_BINARY_DIR (unless it is absolute), and the paths in the
503 DEPFILE are also relative to CMAKE_CURRENT_BINARY_DIR. CMake automati‐
504 cally transforms the paths in the DEPFILE (unless they are absolute)
505 after the custom command is run. The file listed in DEPFILE is not mod‐
506 ified in any way. Instead, CMake writes the transformation to its own
507 internal file, and passes this internal file to Ninja's depfile vari‐
508 able. This transformation happens regardless of whether or not DEPFILE
509 is relative, and regardless of whether or not add_custom_command() is
510 called from a subdirectory.
511 The OLD behavior for this policy is to pass the DEPFILE to Ninja unal‐
513 tered. The NEW behavior for this policy is to transform the DEPFILE af‐
514 ter running the custom command. The status of CMP0116 is recorded at
515 the time of the custom command's creation, and you can have custom com‐
516 mands in the same directory with different values for CMP0116 by set‐
517 ting the policy before each custom command.
518 This policy was introduced in CMake version 3.20. Unlike most poli‐
520 cies, CMake version 3.22.2 does not warn by default when this policy is
521 not set (unless DEPFILE is used in a subdirectory) and simply uses OLD
522 behavior. See documentation of the CMAKE_POLICY_WARNING_CMP0116 vari‐
523 able to control the warning.
524 CMP0115
526 New in version 3.20.
527 Source file extensions must be explicit.
530 In CMake 3.19 and below, if a source file could not be found by the
532 name specified, it would append a list of known extensions to the name
533 to see if the file with the extension could be found. For example, this
534 would allow the user to run:
535 add_executable(exe main)
537 and put main.c in the executable without specifying the extension.
539 Starting in CMake 3.20, CMake prefers all source files to have their
541 extensions explicitly listed:
542 add_executable(exe main.c)
544 The OLD behavior for this policy is to implicitly append known exten‐
546 sions to source files if they can't be found. The NEW behavior of this
547 policy is to not append known extensions and require them to be ex‐
548 plicit.
549 This policy was introduced in CMake version 3.20. CMake version 3.22.2
551 warns when the policy is not set and uses OLD behavior. Use the
552 cmake_policy() command to set it to OLD or NEW explicitly.
553 NOTE:
555 The OLD behavior of a policy is deprecated by definition and may be
556 removed in a future version of CMake.
557
559 CMP0114
560 New in version 3.19.
561 ExternalProject step targets fully adopt their steps.
564 The ExternalProject_Add() STEP_TARGETS option, and the ExternalPro‐
566 ject_Add_StepTargets() function, can be used to create build targets
567 for individual steps of an external project.
568 In CMake 3.18 and below, step targets have some limitations:
570 • Step targets always depend on targets named by the ExternalPro‐
572 ject_Add() DEPENDS option even though not all steps need them. In
573 order to allow step targets to be created without those dependencies,
574 the ExternalProject_Add() INDEPENDENT_STEP_TARGETS option or the Ex‐
575 ternalProject_Add_StepTargets() NO_DEPENDS option may be used. How‐
576 ever, adding such "independent" step targets makes sense only for
577 specific steps such as download, update, and patch because they do
578 not need any of the external project's build dependencies. Further‐
579 more, it does not make sense to create independent step targets for
580 steps that depend on non-independent steps. Such rules are not en‐
581 forced, and projects that do not follow them can generate build sys‐
582 tems with confusing and generator-specific behavior.
583 • Step targets hold copies of the custom commands implementing their
585 steps that are separate from the copies in the primary target created
586 by ExternalProject_Add(), and the primary target does not depend on
587 the step targets. In parallel builds that drive the primary target
588 and step targets concurrently, multiple copies of the steps' commands
589 may run concurrently and race each other.
590 Also, prior to policy CMP0113, the step targets generated by Makefile
592 Generators also contain all the custom commands on which their step
593 depends. This can lead to repeated execution of those steps even in
594 serial builds.
595 In CMake 3.19 and above, the ExternalProject module prefers a revised
597 design to address these problems:
598 • Each step is classified as "independent" if it does not depend on
600 other targets named by the ExternalProject_Add() DEPENDS. The prede‐
601 fined steps are automatically classified by default:
602 • The download, update, and patch steps are independent.
604 • The configure, build, test, and install steps are not.
606 For custom steps, the ExternalProject_Add_Step() command provides an
608 INDEPENDENT option to mark them as independent. It is an error to
609 mark a step as independent if it depends on other steps that are not.
610 Note that this use of the term "independent" refers only to indepen‐
611 dence from external targets and is orthogonal to a step's dependen‐
612 cies on other steps.
613 • Step targets created by the ExternalProject_Add() STEP_TARGETS option
615 or the ExternalProject_Add_Step() function are now independent if and
616 only if their steps are marked as independent. The ExternalPro‐
617 ject_Add() INDEPENDENT_STEP_TARGETS option and ExternalPro‐
618 ject_Add_StepTargets() NO_DEPENDS option are no longer allowed.
619 • Step targets, when created, are fully responsible for holding the
621 custom commands implementing their steps. The primary target created
622 by ExternalProject_Add() depends on the step targets, and the step
623 targets depend on each other. The target-level dependencies match
624 the file-level dependencies used by the custom commands for each
625 step.
626 When the ExternalProject_Add() UPDATE_DISCONNECTED or TEST_EX‐
628 CLUDE_FROM_MAIN option is used, or the ExternalProject_Add_Step() EX‐
629 CLUDE_FROM_MAIN option is used for a custom step, some step targets
630 may be created automatically. These are needed to hold the steps
631 commonly depended upon by the primary target and the disconnected
632 step targets.
633 Policy CMP0114 provides compatibility for projects that have not been
635 updated to expect the new behavior. The OLD behavior for this policy
636 is to use the above-documented behavior from 3.18 and below. The NEW
637 behavior for this policy is to use the above-documented behavior pre‐
638 ferred by 3.19 and above.
639 This policy was introduced in CMake version 3.19. CMake version 3.22.2
641 warns when the policy is not set and uses OLD behavior. Use the
642 cmake_policy() command to set it to OLD or NEW explicitly.
643 CMP0113
645 New in version 3.19.
646 Makefile Generators do not repeat custom commands from target dependen‐
649 cies.
650 Consider a chain of custom commands split across two dependent targets:
652 add_custom_command(OUTPUT output-not-created
654 COMMAND ... DEPENDS ...)
655 set_property(SOURCE output-not-created PROPERTY SYMBOLIC 1)
656 add_custom_command(OUTPUT output-created
657 COMMAND ... DEPENDS ${CMAKE_CURRENT_BINARY_DIR}/output-not-created)
658 add_custom_target(first DEPENDS output-not-created)
659 add_custom_target(second DEPENDS output-created)
660 add_dependencies(second first)
661 In CMake 3.18 and lower, the Makefile generators put a copy of both
663 custom commands in the Makefile for target second even though its de‐
664 pendency on target first ensures that the first custom command runs be‐
665 fore the second. Running make second would cause the first custom com‐
666 mand to run once in the first target and then again in the second tar‐
667 get.
668 CMake 3.19 and above prefer to not duplicate custom commands in a tar‐
670 get that are already generated in other targets on which the target de‐
671 pends (directly or indirectly). This policy provides compatibility for
672 projects that have not been updated to expect the new behavior. In
673 particular, projects that relied on the duplicate execution or that did
674 not properly set the SYMBOLIC source file property may be affected.
675 The OLD behavior for this policy is to duplicate custom commands in de‐
677 pendent targets. The NEW behavior of this policy is to not duplicate
678 custom commands in dependent targets.
679 This policy was introduced in CMake version 3.19. Unlike many poli‐
681 cies, CMake version 3.22.2 does not warn when this policy is not set
682 and simply uses OLD behavior.
683 NOTE:
685 The OLD behavior of a policy is deprecated by definition and may be
686 removed in a future version of CMake.
687 CMP0112
689 New in version 3.19.
690 Target file component generator expressions do not add target dependen‐
693 cies.
694 The following target-based generator expressions that query for direc‐
696 tory or file name components no longer add a dependency on the evalu‐
697 ated target.
698 • TARGET_FILE_NAME
700 • TARGET_FILE_DIR
702 • TARGET_LINKER_FILE_BASE_NAME
704 • TARGET_LINKER_FILE_NAME
706 • TARGET_LINKER_FILE_DIR
708 • TARGET_SONAME_FILE_NAME
710 • TARGET_SONAME_FILE_DIR
712 • TARGET_PDB_FILE_NAME
714 • TARGET_PDB_FILE_DIR
716 • TARGET_BUNDLE_DIR
718 • TARGET_BUNDLE_CONTENT_DIR
720 In CMake 3.18 and lower a dependency on the evaluated target of the
722 above generator expressions would always be added. CMake 3.19 and
723 above prefer to not add this dependency. This policy provides compati‐
724 bility for projects that have not been updated to expect the new behav‐
725 ior.
726 The OLD behavior for this policy is to add a dependency on the evalu‐
728 ated target for the above generator expressions. The NEW behavior of
729 this policy is to not add a dependency on the evaluated target for the
730 above generator expressions.
731 This policy was introduced in CMake version 3.19. Unlike many poli‐
733 cies, CMake version 3.22.2 does not warn by default when this policy is
734 not set and simply uses OLD behavior. See documentation of the
735 CMAKE_POLICY_WARNING_CMP0112 variable to control the warning.
736 NOTE:
738 The OLD behavior of a policy is deprecated by definition and may be
739 removed in a future version of CMake.
740 CMP0111
742 New in version 3.19.
743 An imported target missing its location property fails during genera‐
746 tion.
747 Imported Targets for library files and executables require that their
749 location on disk is specified in a target property such as IMPORTED_LO‐
750 CATION, IMPORTED_IMPLIB, or a per-configuration equivalent. If a
751 needed location property is not set, CMake 3.18 and below generate the
752 string <TARGET_NAME>-NOTFOUND in its place, which results in failures
753 of the corresponding rules at build time. CMake 3.19 and above prefer
754 instead to raise an error during generation. This policy provides com‐
755 patibility for projects that have not been updated to expect the new
756 behavior.
757 The OLD behavior of this policy is to generate the location of an im‐
759 ported unknown, static or shared library target as <TARGET_NAME>-NOT‐
760 FOUND if not set. The NEW behavior is to raise an error.
761 This policy was introduced in CMake version 3.19. CMake version 3.22.2
763 warns when the policy is not set and uses OLD behavior. Use the
764 cmake_policy() command to set it to OLD or NEW explicitly.
765 NOTE:
767 The OLD behavior of a policy is deprecated by definition and may be
768 removed in a future version of CMake.
769 CMP0110
771 New in version 3.19.
772 add_test() supports arbitrary characters in test names.
775 add_test() can now (officially) create tests with whitespace and other
777 special characters in its name. Before CMake version 3.19 that was not
778 allowed, however, it was possible to work around this limitation by ex‐
779 plicitly putting escaped quotes around the test's name in the add_test
780 command.
781 Although never officially supported several projects in the wild found
783 and implemented this workaround. However, the new change which offi‐
784 cially allows the add_test command to support whitespace and other spe‐
785 cial characters in test names now breaks that workaround. In order for
786 these projects to work smoothly with newer CMake versions, this policy
787 was introduced.
788 The OLD behavior of this policy is to still prevent add_test from han‐
790 dling whitespace and special characters properly (if not using the men‐
791 tioned workaround). The NEW behavior on the other hand allows names
792 with whitespace and special characters for tests created by add_test.
793 This policy was introduced in CMake version 3.19. CMake version 3.22.2
795 warns when the policy is not set and uses OLD behavior. Use the
796 cmake_policy() command to set it to OLD or NEW explicitly.
797 CMP0109
799 New in version 3.19.
800 find_program() requires permission to execute but not to read.
803 In CMake 3.18 and below, the find_program() command on UNIX would find
805 files that are readable without requiring execute permission, and would
806 not find files that are executable without read permission. In CMake
807 3.19 and above, find_program now prefers to require execute permission
808 but not read permission. This policy provides compatibility with
809 projects that have not been updated to expect the new behavior.
810 The OLD behavior for this policy is for find_program to require read
812 permission but not execute permission. The NEW behavior for this pol‐
813 icy is for find_program to require execute permission but not read per‐
814 mission.
815 This policy was introduced in CMake version 3.19. CMake version 3.22.2
817 warns when the policy is not set and uses OLD behavior. Use the
818 cmake_policy() command to set it to OLD or NEW explicitly.
819 NOTE:
821 The OLD behavior of a policy is deprecated by definition and may be
822 removed in a future version of CMake.
823
825 CMP0108
826 New in version 3.18.
827 A target is not allowed to link to itself even through an ALIAS target.
830 In CMake 3.17 and below, a target can link to a target aliased to it‐
832 self.
833 The OLD behavior for this policy is to allow a target to link to a tar‐
835 get aliased to itself.
836 The NEW behavior of this policy is to prevent a target to link to it‐
838 self through an ALIAS target.
839 This policy was introduced in CMake version 3.17. Use the cmake_pol‐
841 icy() command to set it to OLD or NEW explicitly. Unlike many poli‐
842 cies, CMake version 3.22.2 does not warn when this policy is not set
843 and simply uses OLD behavior.
844 NOTE:
846 The OLD behavior of a policy is deprecated by definition and may be
847 removed in a future version of CMake.
848 CMP0107
850 New in version 3.18.
851 It is not allowed to create an ALIAS target with the same name as an
854 another target.
855 In CMake 3.17 and below, an ALIAS target can overwrite silently an ex‐
857 isting target with the same name.
858 The OLD behavior for this policy is to allow target overwrite.
860 The NEW behavior of this policy is to prevent target overwriting.
862 This policy was introduced in CMake version 3.17. Use the cmake_pol‐
864 icy() command to set it to OLD or NEW explicitly. Unlike many poli‐
865 cies, CMake version 3.22.2 does not warn when this policy is not set
866 and simply uses OLD behavior.
867 NOTE:
869 The OLD behavior of a policy is deprecated by definition and may be
870 removed in a future version of CMake.
871 CMP0106
873 New in version 3.18.
874 The Documentation module is removed.
877 The Documentation was added as a support mechanism for the VTK project
879 and was tuned for that project. Instead of CMake providing this module
880 with (now old) VTK patterns for cache variables and required packages,
881 the module is now deprecated by CMake itself.
882 The OLD behavior of this policy is for Documentation to add cache vari‐
884 ables and find VTK documentation dependent packages. The NEW behavior
885 is to act as an empty module.
886 This policy was introduced in CMake version 3.18. CMake version 3.22.2
888 warns when the policy is not set and uses OLD behavior. Use the
889 cmake_policy() command to set it to OLD or NEW explicitly.
890 NOTE:
892 The OLD behavior of a policy is deprecated by definition and may be
893 removed in a future version of CMake.
894 CMP0105
896 New in version 3.18.
897 LINK_OPTIONS and INTERFACE_LINK_OPTIONS target properties are now used
900 for the device link step.
901 In CMake 3.17 and below, link options are not used by the device link
903 step.
904 The OLD behavior for this policy is to ignore the link options.
906 The NEW behavior of this policy is to use the link options during the
908 device link step.
909 This policy was introduced in CMake version 3.17. Use the cmake_pol‐
911 icy() command to set it to OLD or NEW explicitly. Unlike many poli‐
912 cies, CMake version 3.22.2 does not warn when this policy is not set
913 and simply uses OLD behavior.
914 NOTE:
916 The OLD behavior of a policy is deprecated by definition and may be
917 removed in a future version of CMake.
918 CMP0104
920 New in version 3.18.
921 Initialize CMAKE_CUDA_ARCHITECTURES when CMAKE_CUDA_COMPILER_ID is
924 NVIDIA. Raise an error if CUDA_ARCHITECTURES is empty.
925 CMAKE_CUDA_ARCHITECTURES introduced in CMake 3.18 is used to initialize
927 CUDA_ARCHITECTURES, which passes correct code generation flags to the
928 CUDA compiler.
929 Previous to this users had to manually specify the code generation
931 flags. This policy is for backwards compatibility with manually speci‐
932 fying code generation flags.
933 The OLD behavior for this policy is to not initialize CMAKE_CUDA_ARCHI‐
935 TECTURES when CMAKE_CUDA_COMPILER_ID is NVIDIA. Empty CUDA_ARCHITEC‐
936 TURES is allowed.
937 The NEW behavior of this policy is to initialize CMAKE_CUDA_ARCHITEC‐
939 TURES when CMAKE_CUDA_COMPILER_ID is NVIDIA and raise an error if
940 CUDA_ARCHITECTURES is empty during generation.
941 If CUDA_ARCHITECTURES is set to a false value no architectures flags
943 are passed to the compiler. This is intended to support packagers and
944 the rare cases where full control over the passed flags is required.
945 This policy was introduced in CMake version 3.18. CMake version 3.22.2
947 warns when the policy is not set and uses OLD behavior. Use the
948 cmake_policy() command to set it to OLD or NEW explicitly.
949 NOTE:
951 The OLD behavior of a policy is deprecated by definition and may be
952 removed in a future version of CMake.
953 Examples
955 set_target_properties(tgt PROPERTIES CUDA_ARCHITECTURES "35;50;72")
956 Generates code for real and virtual architectures 30, 50 and 72.
958 set_property(TARGET tgt PROPERTY CUDA_ARCHITECTURES 70-real 72-virtual)
960 Generates code for real architecture 70 and virtual architecture 72.
962 set_property(TARGET tgt PROPERTY CUDA_ARCHITECTURES OFF)
964 CMake will not pass any architecture flags to the compiler.
966 CMP0103
968 New in version 3.18.
969 Multiple calls to export() command with same FILE without APPEND is no
972 longer allowed.
973 In CMake 3.17 and below, multiple calls to export() command with the
975 same FILE without APPEND are accepted silently but only the last occur‐
976 rence is taken into account during the generation.
977 The OLD behavior for this policy is to ignore the multiple occurrences
979 of
980 export() command except the last one.
981 The NEW behavior of this policy is to raise an error on second call to
983 export() command with same FILE without APPEND.
984 This policy was introduced in CMake version 3.18. CMake version 3.22.2
986 warns when the policy is not set and uses OLD behavior. Use the
987 cmake_policy() command to set it to OLD or NEW explicitly.
988 NOTE:
990 The OLD behavior of a policy is deprecated by definition and may be
991 removed in a future version of CMake.
992
994 CMP0102
995 New in version 3.17.
996 The mark_as_advanced() command no longer creates a cache entry if one
999 does not already exist.
1000 In CMake 3.16 and below, if a variable was not defined at all or just
1002 defined locally, the mark_as_advanced() command would create a new
1003 cache entry with an UNINITIALIZED type and no value. When a find_path()
1004 (or other similar find_ command) would next run, it would find this un‐
1005 defined cache entry and set it up with an empty string value. This
1006 process would end up deleting the local variable in the process (due to
1007 the way the cache works), effectively clearing any stored find_ results
1008 that were only available in the local scope.
1009 The OLD behavior for this policy is to create the empty cache defini‐
1011 tion. The NEW behavior of this policy is to ignore variables which do
1012 not already exist in the cache.
1013 This policy was introduced in CMake version 3.17. Use the cmake_pol‐
1015 icy() command to set it to OLD or NEW explicitly. Unlike many poli‐
1016 cies, CMake version 3.22.2 does not warn when this policy is not set
1017 and simply uses OLD behavior. See documentation of the CMAKE_POL‐
1018 ICY_WARNING_CMP0102 variable to control the warning.
1019 NOTE:
1021 The OLD behavior of a policy is deprecated by definition and may be
1022 removed in a future version of CMake.
1023 CMP0101
1025 New in version 3.17.
1026 target_compile_options() now honors BEFORE keyword in all scopes.
1029 In CMake 3.16 and below the target_compile_options() ignores the BEFORE
1031 keyword in private scope. CMake 3.17 and later honors BEFORE keyword in
1032 all scopes. This policy provides compatibility for projects that have
1033 not been updated to expect the new behavior.
1034 The OLD behavior for this policy is to not honor BEFORE keyword in pri‐
1036 vate scope. The NEW behavior of this policy is to honor BEFORE keyword
1037 in all scopes.
1038 This policy was introduced in CMake version 3.17. Use the cmake_pol‐
1040 icy() command to set it to OLD or NEW explicitly. Unlike many poli‐
1041 cies, CMake version 3.22.2 does not warn when this policy is not set
1042 and simply uses OLD behavior.
1043 NOTE:
1045 The OLD behavior of a policy is deprecated by definition and may be
1046 removed in a future version of CMake.
1047 CMP0100
1049 New in version 3.17.
1050 Let AUTOMOC and AUTOUIC process header files that end with a .hh exten‐
1053 sion.
1054 Since version 3.17, CMake processes header files that end with a .hh
1056 extension in AUTOMOC and AUTOUIC. In earlier CMake versions, these
1057 header files were ignored by AUTOMOC and AUTOUIC.
1058 This policy affects how header files that end with a .hh extension get
1060 treated in AUTOMOC and AUTOUIC.
1061 The OLD behavior for this policy is to ignore .hh header files in AUTO‐
1063 MOC and AUTOUIC.
1064 The NEW behavior for this policy is to process .hh header files in AU‐
1066 TOMOC and AUTOUIC just like other header files.
1067 NOTE:
1069 To silence the CMP0100 warning source files can be excluded from AU‐
1070 TOMOC and AUTOUIC processing by setting the source file properties
1071 SKIP_AUTOMOC, SKIP_AUTOUIC or SKIP_AUTOGEN.
1072 # Source skip example:
1074 set_property(SOURCE /path/to/file1.hh PROPERTY SKIP_AUTOMOC ON)
1075 set_property(SOURCE /path/to/file2.hh PROPERTY SKIP_AUTOUIC ON)
1076 set_property(SOURCE /path/to/file3.hh PROPERTY SKIP_AUTOGEN ON)
1077 This policy was introduced in CMake version 3.17.0. CMake version
1079 3.22.2 warns when the policy is not set and uses OLD behavior. Use the
1080 cmake_policy() command to set it to OLD or NEW explicitly.
1081 NOTE:
1083 The OLD behavior of a policy is deprecated by definition and may be
1084 removed in a future version of CMake.
1085 CMP0099
1087 New in version 3.17.
1088 Target link properties INTERFACE_LINK_OPTIONS, INTERFACE_LINK_DIRECTO‐
1091 RIES and INTERFACE_LINK_DEPENDS are now transitive over private depen‐
1092 dencies of static libraries.
1093 In CMake 3.16 and below the interface link properties attached to li‐
1095 braries are not propagated for private dependencies of static li‐
1096 braries. Only the libraries themselves are propagated to link the de‐
1097 pendent binary. CMake 3.17 and later prefer to propagate all interface
1098 link properties. This policy provides compatibility for projects that
1099 have not been updated to expect the new behavior.
1100 The OLD behavior for this policy is to not propagate interface link
1102 properties. The NEW behavior of this policy is to propagate interface
1103 link properties.
1104 This policy was introduced in CMake version 3.17. Use the cmake_pol‐
1106 icy() command to set it to OLD or NEW explicitly. Unlike many poli‐
1107 cies, CMake version 3.22.2 does not warn when this policy is not set
1108 and simply uses OLD behavior.
1109 NOTE:
1111 The OLD behavior of a policy is deprecated by definition and may be
1112 removed in a future version of CMake.
1113 CMP0098
1115 New in version 3.17.
1116 FindFLEX runs flex in directory CMAKE_CURRENT_BINARY_DIR when execut‐
1119 ing.
1120 The module provides a FLEX_TARGET macro which generates FLEX output.
1122 In CMake 3.16 and below the macro would generate a custom command that
1123 runs flex in the current source directory. CMake 3.17 and later prefer
1124 to run it in the build directory and use CMAKE_CURRENT_BINARY_DIR as
1125 the WORKING_DIRECTORY of its add_custom_command() invocation. This en‐
1126 sures that any implicitly generated file is written relative to the
1127 build tree rather than the source tree, unless the generated file is
1128 provided as absolute path.
1129 This policy provides compatibility for projects that have not been up‐
1131 dated to expect the new behavior.
1132 The OLD behavior for this policy is for FLEX_TARGET to use the current
1134 source directory for the WORKING_DIRECTORY and where to generate im‐
1135 plicit files. The NEW behavior of this policy is to use the current bi‐
1136 nary directory for the WORKING_DIRECTORY relative to which implicit
1137 files are generated unless provided as absolute path.
1138 This policy was introduced in CMake version 3.17. Use the cmake_pol‐
1140 icy() command to set it to OLD or NEW explicitly. Unlike many poli‐
1141 cies, CMake version 3.22.2 does not warn when this policy is not set
1142 and simply uses OLD behavior.
1143 NOTE:
1145 The OLD behavior of a policy is deprecated by definition and may be
1146 removed in a future version of CMake.
1147
1149 CMP0097
1150 New in version 3.16.
1151 ExternalProject_Add() with GIT_SUBMODULES "" initializes no submodules.
1154 The module provides a GIT_SUBMODULES option which controls what submod‐
1156 ules to initialize and update. Starting with CMake 3.16, explicitly
1157 setting GIT_SUBMODULES to an empty string means no submodules will be
1158 initialized or updated.
1159 This policy provides compatibility for projects that have not been up‐
1161 dated to expect the new behavior.
1162 The OLD behavior for this policy is for GIT_SUBMODULES when set to an
1164 empty string to initialize and update all git submodules. The NEW be‐
1165 havior for this policy is for GIT_SUBMODULES when set to an empty
1166 string to initialize and update no git submodules.
1167 This policy was introduced in CMake version 3.16. Use the cmake_pol‐
1169 icy() command to set it to OLD or NEW explicitly. Unlike most poli‐
1170 cies, CMake version 3.22.2 does not warn when this policy is not set
1171 and simply uses OLD behavior.
1172 CMP0096
1174 New in version 3.16.
1175 The project() command preserves leading zeros in version components.
1178 When a VERSION <major>[.<minor>[.<patch>[.<tweak>]]]] argument is given
1180 to the project() command, it stores the version string in the
1181 PROJECT_VERSION variable and stores individual integer version compo‐
1182 nents in PROJECT_VERSION_{MAJOR,MINOR,PATCH,TWEAK} variables (see pol‐
1183 icy CMP0048). CMake 3.15 and below dropped leading zeros from each
1184 component. CMake 3.16 and higher prefer to preserve leading zeros.
1185 This policy provides compatibility for projects that have not been up‐
1186 dated to expect the new behavior.
1187 The OLD behavior of this policy drops leading zeros in all components,
1189 e.g. such that version 1.07.06 becomes 1.7.6. The NEW behavior of
1190 this policy preserves the leading zeros in all components, such that
1191 version 1.07.06 remains unchanged.
1192 This policy was introduced in CMake version 3.16. Unlike many poli‐
1194 cies, CMake version 3.22.2 does not warn when this policy is not set
1195 and simply uses the OLD behavior. Use the cmake_policy() command to
1196 set it to OLD or NEW explicitly.
1197 NOTE:
1199 The OLD behavior of a policy is deprecated by definition and may be
1200 removed in a future version of CMake.
1201 CMP0095
1203 New in version 3.16.
1204 RPATH entries are properly escaped in the intermediary CMake install
1207 script.
1208 In CMake 3.15 and earlier, RPATH entries set via CMAKE_INSTALL_RPATH or
1210 via INSTALL_RPATH have not been escaped before being inserted into the
1211 cmake_install.cmake script. Dynamic linkers on ELF-based systems (e.g.
1212 Linux and FreeBSD) allow certain keywords in RPATH entries, such as
1213 ${ORIGIN} (More details are available in the ld.so man pages on those
1214 systems). The syntax of these keywords can match CMake's variable syn‐
1215 tax. In order to not be substituted (usually to an empty string) al‐
1216 ready by the intermediary cmake_install.cmake script, the user had to
1217 double-escape such RPATH keywords, e.g. set(CMAKE_INSTALL_RPATH
1218 "\\\${ORIGIN}/../lib"). Since the intermediary cmake_install.cmake
1219 script is an implementation detail of CMake, CMake 3.16 and later will
1220 make sure RPATH entries are inserted literally by escaping any coinci‐
1221 dental CMake syntax.
1222 The OLD behavior of this policy is to not escape RPATH entries in the
1224 intermediary cmake_install.cmake script. The NEW behavior is to prop‐
1225 erly escape coincidental CMake syntax in RPATH entries when generating
1226 the intermediary cmake_install.cmake script.
1227 This policy was introduced in CMake version 3.16. CMake version 3.22.2
1229 warns when the policy is not set and detected usage of CMake-like syn‐
1230 tax and uses OLD behavior. Use the cmake_policy() command to set it to
1231 OLD or NEW explicitly.
1232 NOTE:
1234 The OLD behavior of a policy is deprecated by definition and may be
1235 removed in a future version of CMake.
1236
1238 CMP0094
1239 New in version 3.15.
1240 Modules FindPython3, FindPython2 and FindPython use LOCATION for lookup
1243 strategy.
1244 Starting with CMake 3.15, Modules FindPython3, FindPython2 and Find‐
1246 Python set value LOCATION for, respectively, variables
1247 Python3_FIND_STRATEGY, Python2_FIND_STRATEGY and Python_FIND_STRATEGY.
1248 This policy provides compatibility with projects that expect the legacy
1249 behavior.
1250 The OLD behavior for this policy set value VERSION for variables
1252 Python3_FIND_STRATEGY, Python2_FIND_STRATEGY and Python_FIND_STRATEGY.
1253 This policy was introduced in CMake version 3.15. Use the cmake_pol‐
1255 icy() command to set it to OLD or NEW explicitly. Unlike many poli‐
1256 cies, CMake version 3.22.2 does not warn when this policy is not set
1257 and simply uses the OLD behavior.
1258 NOTE:
1260 The OLD behavior of a policy is deprecated by definition and may be
1261 removed in a future version of CMake.
1262 CMP0093
1264 New in version 3.15.
1265 FindBoost reports Boost_VERSION in x.y.z format.
1268 In CMake 3.14 and below the module would report the Boost version num‐
1270 ber as specified in the preprocessor definition BOOST_VERSION in the
1271 boost/version.hpp file. In CMake 3.15 and later it is preferred that
1272 the reported version number matches the x.y.z format reported by the
1273 CMake package shipped with Boost 1.70.0 and later. The macro value is
1274 still reported in the Boost_VERSION_MACRO variable.
1275 The OLD behavior for this policy is for FindBoost to report Boost_VER‐
1277 SION as specified in the preprocessor definition BOOST_VERSION in
1278 boost/version.hpp. The NEW behavior for this policy is for FindBoost to
1279 report Boost_VERSION in x.y.z format.
1280 This policy was introduced in CMake version 3.15. Use the cmake_pol‐
1282 icy() command to set it to OLD or NEW explicitly. Unlike many poli‐
1283 cies, CMake version 3.22.2 does not warn when this policy is not set
1284 and simply uses the OLD behavior.
1285 NOTE:
1287 The OLD behavior of a policy is deprecated by definition and may be
1288 removed in a future version of CMake.
1289 CMP0092
1291 New in version 3.15.
1292 MSVC warning flags are not in CMAKE_<LANG>_FLAGS by default.
1295 When using MSVC-like compilers in CMake 3.14 and below, warning flags
1297 like /W3 are added to CMAKE_<LANG>_FLAGS by default. This is problem‐
1298 atic for projects that want to choose a different warning level pro‐
1299 grammatically. In particular, it requires string editing of the
1300 CMAKE_<LANG>_FLAGS variables with knowledge of the CMake builtin de‐
1301 faults so they can be replaced.
1302 CMake 3.15 and above prefer to leave out warning flags from the value
1304 of CMAKE_<LANG>_FLAGS by default.
1305 This policy provides compatibility with projects that have not been up‐
1307 dated to expect the lack of warning flags. The policy setting takes
1308 effect as of the first project() or enable_language() command that ini‐
1309 tializes CMAKE_<LANG>_FLAGS for a given language <LANG>.
1310 NOTE:
1312 Once the policy has taken effect at the top of a project for a given
1313 language, that choice must be used throughout the tree for that lan‐
1314 guage. In projects that have nested projects in subdirectories, be
1315 sure to convert everything together.
1316 The OLD behavior for this policy is to place MSVC warning flags in the
1318 default CMAKE_<LANG>_FLAGS cache entries. The NEW behavior for this
1319 policy is to not place MSVC warning flags in the default cache entries.
1320 This policy was introduced in CMake version 3.15. Use the cmake_pol‐
1322 icy() command to set it to OLD or NEW explicitly. Unlike many poli‐
1323 cies, CMake version 3.22.2 does not warn when this policy is not set
1324 and simply uses OLD behavior.
1325 NOTE:
1327 The OLD behavior of a policy is deprecated by definition and may be
1328 removed in a future version of CMake.
1329 CMP0091
1331 New in version 3.15.
1332 MSVC runtime library flags are selected by an abstraction.
1335 Compilers targeting the MSVC ABI have flags to select the MSVC runtime
1337 library. Runtime library selection typically varies with build config‐
1338 uration because there is a separate runtime library for Debug builds.
1339 In CMake 3.14 and below, MSVC runtime library selection flags are added
1341 to the default CMAKE_<LANG>_FLAGS_<CONFIG> cache entries by CMake auto‐
1342 matically. This allows users to edit their cache entries to adjust the
1343 flags. However, the presence of such default flags is problematic for
1344 projects that want to choose a different runtime library programmati‐
1345 cally. In particular, it requires string editing of the
1346 CMAKE_<LANG>_FLAGS_<CONFIG> variables with knowledge of the CMake
1347 builtin defaults so they can be replaced.
1348 CMake 3.15 and above prefer to leave the MSVC runtime library selection
1350 flags out of the default CMAKE_<LANG>_FLAGS_<CONFIG> values and instead
1351 offer a first-class abstraction. The CMAKE_MSVC_RUNTIME_LIBRARY vari‐
1352 able and MSVC_RUNTIME_LIBRARY target property may be set to select the
1353 MSVC runtime library. If they are not set then CMake uses the default
1354 value MultiThreaded$<$<CONFIG:Debug>:Debug>DLL which is equivalent to
1355 the original flags.
1356 This policy provides compatibility with projects that have not been up‐
1358 dated to be aware of the abstraction. The policy setting takes effect
1359 as of the first project() or enable_language() command that enables a
1360 language whose compiler targets the MSVC ABI.
1361 NOTE:
1363 Once the policy has taken effect at the top of a project, that
1364 choice must be used throughout the tree. In projects that have
1365 nested projects in subdirectories, be sure to convert everything to‐
1366 gether.
1367 The OLD behavior for this policy is to place MSVC runtime library flags
1369 in the default CMAKE_<LANG>_FLAGS_<CONFIG> cache entries and ignore the
1370 CMAKE_MSVC_RUNTIME_LIBRARY abstraction. The NEW behavior for this pol‐
1371 icy is to not place MSVC runtime library flags in the default cache en‐
1372 tries and use the abstraction instead.
1373 This policy was introduced in CMake version 3.15. Use the cmake_pol‐
1375 icy() command to set it to OLD or NEW explicitly. Unlike many poli‐
1376 cies, CMake version 3.22.2 does not warn when this policy is not set
1377 and simply uses OLD behavior.
1378 NOTE:
1380 The OLD behavior of a policy is deprecated by definition and may be
1381 removed in a future version of CMake.
1382 CMP0090
1384 New in version 3.15.
1385 export(PACKAGE) does not populate package registry by default.
1388 In CMake 3.14 and below the export(PACKAGE) command populated the user
1390 package registry by default and users needed to set the CMAKE_EX‐
1391 PORT_NO_PACKAGE_REGISTRY to disable it, e.g. in automated build and
1392 packaging environments. Since the user package registry is stored out‐
1393 side the build tree, this side effect should not be enabled by default.
1394 Therefore CMake 3.15 and above prefer that export(PACKAGE) does nothing
1395 unless an explicit CMAKE_EXPORT_PACKAGE_REGISTRY variable is set to en‐
1396 able it. This policy provides compatibility with projects that have
1397 not been updated.
1398 The OLD behavior for this policy is for export(PACKAGE) command to pop‐
1400 ulate the user package registry unless CMAKE_EXPORT_NO_PACKAGE_REGISTRY
1401 is enabled. The NEW behavior is for export(PACKAGE) command to do
1402 nothing unless the CMAKE_EXPORT_PACKAGE_REGISTRY is enabled.
1403 This policy was introduced in CMake version 3.15. Use the cmake_pol‐
1405 icy() command to set it to OLD or NEW explicitly. Unlike most poli‐
1406 cies, CMake version 3.22.2 does not warn when this policy is not set
1407 and simply uses OLD behavior.
1408 NOTE:
1410 The OLD behavior of a policy is deprecated by definition and may be
1411 removed in a future version of CMake.
1412 CMP0089
1414 New in version 3.15.
1415 Compiler id for IBM Clang-based XL compilers is now XLClang.
1418 CMake 3.15 and above recognize that IBM's Clang-based XL compilers that
1420 define __ibmxl__ are a new front-end distinct from xlc with a different
1421 command line and set of capabilities. CMake now prefers to present
1422 this to projects by setting the CMAKE_<LANG>_COMPILER_ID variable to
1423 XLClang instead of XL. However, existing projects may assume the com‐
1424 piler id for Clang-based XL is just XL as it was in CMake versions
1425 prior to 3.15. Therefore this policy determines for Clang-based XL
1426 compilers which compiler id to report in the CMAKE_<LANG>_COMPILER_ID
1427 variable after language <LANG> is enabled by the project() or en‐
1428 able_language() command. The policy must be set prior to the invoca‐
1429 tion of either command.
1430 The OLD behavior for this policy is to use compiler id XL. The NEW be‐
1432 havior for this policy is to use compiler id XLClang.
1433 This policy was introduced in CMake version 3.15. Use the cmake_pol‐
1435 icy() command to set this policy to OLD or NEW explicitly. Unlike most
1436 policies, CMake version 3.22.2 does not warn by default when this pol‐
1437 icy is not set and simply uses OLD behavior. See documentation of the
1438 CMAKE_POLICY_WARNING_CMP0089 variable to control the warning.
1439 NOTE:
1441 The OLD behavior of a policy is deprecated by definition and may be
1442 removed in a future version of CMake.
1443
1445 CMP0088
1446 New in version 3.14.
1447 FindBISON runs bison in CMAKE_CURRENT_BINARY_DIR when executing.
1450 The module provides a BISON_TARGET macro which generates BISON output.
1452 In CMake 3.13 and below the macro would generate a custom command that
1453 runs bison in the source directory. CMake 3.14 and later prefer to run
1454 it in the build directory and use CMAKE_CURRENT_BINARY_DIR as the WORK‐
1455 ING_DIRECTORY of its add_custom_command() invocation. This ensures
1456 that any implicitly generated file is written to the build tree rather
1457 than the source.
1458 This policy provides compatibility for projects that have not been up‐
1460 dated to expect the new behavior.
1461 The OLD behavior for this policy is for BISON_TARGET to use the current
1463 source directory for the WORKING_DIRECTORY and where to generate im‐
1464 plicit files. The NEW behavior of this policy is to use the current bi‐
1465 nary directory for the WORKING_DIRECTORY and where to generate implicit
1466 files.
1467 This policy was introduced in CMake version 3.14. Use the cmake_pol‐
1469 icy() command to set it to OLD or NEW explicitly. Unlike most poli‐
1470 cies, CMake version 3.22.2 does not warn when this policy is not set
1471 and simply uses OLD behavior.
1472 NOTE:
1474 The OLD behavior of a policy is deprecated by definition and may be
1475 removed in a future version of CMake.
1476 CMP0087
1478 New in version 3.14.
1479 install(CODE) and install(SCRIPT) support generator expressions.
1482 In CMake 3.13 and earlier, install(CODE) and install(SCRIPT) did not
1484 evaluate generator expressions. CMake 3.14 and later will evaluate
1485 generator expressions for install(CODE) and install(SCRIPT).
1486 The OLD behavior of this policy is for install(CODE) and in‐
1488 stall(SCRIPT) to not evaluate generator expressions. The NEW behavior
1489 is to evaluate generator expressions for install(CODE) and in‐
1490 stall(SCRIPT).
1491 Note that it is the value of this policy setting at the end of the di‐
1493 rectory scope that is important, not its setting at the time of the
1494 call to install(CODE) or install(SCRIPT). This has implications for
1495 calling these commands from places that have their own policy scope but
1496 not their own directory scope (e.g. from files brought in via include()
1497 rather than add_subdirectory()).
1498 This policy was introduced in CMake version 3.14. CMake version 3.22.2
1500 warns when the policy is not set and uses OLD behavior. Use the
1501 cmake_policy() command to set it to OLD or NEW explicitly.
1502 NOTE:
1504 The OLD behavior of a policy is deprecated by definition and may be
1505 removed in a future version of CMake.
1506 CMP0086
1508 New in version 3.14.
1509 UseSWIG honors SWIG_MODULE_NAME via -module flag.
1512 Starting with CMake 3.14, UseSWIG passes option -module <module_name>
1514 to SWIG compiler if the file property SWIG_MODULE_NAME is specified.
1515 This policy provides compatibility with projects that expect the legacy
1516 behavior.
1517 The OLD behavior for this policy is to never pass -module option. The
1519 NEW behavior is to pass -module option to SWIG compiler if SWIG_MOD‐
1520 ULE_NAME is specified.
1521 This policy was introduced in CMake version 3.14. CMake version 3.22.2
1523 warns when the policy is not set and uses OLD behavior. Use the
1524 cmake_policy() command to set it to OLD or NEW explicitly.
1525 NOTE:
1527 The OLD behavior of a policy is deprecated by definition and may be
1528 removed in a future version of CMake.
1529 CMP0085
1531 New in version 3.14.
1532 $<IN_LIST:...> handles empty list items.
1535 In CMake 3.13 and lower, the $<IN_LIST:...> generator expression always
1537 returned 0 if the first argument was empty, even if the list contained
1538 an empty item. This behavior is inconsistent with the IN_LIST behavior
1539 of if(), which this generator expression is meant to emulate. CMake
1540 3.14 and later handles this case correctly.
1541 The OLD behavior of this policy is for $<IN_LIST:...> to always return
1543 0 if the first argument is empty. The NEW behavior is to return 1 if
1544 the first argument is empty and the list contains an empty item.
1545 This policy was introduced in CMake version 3.14. CMake version 3.22.2
1547 warns when the policy is not set and uses OLD behavior. Use the
1548 cmake_policy() command to set it to OLD or NEW explicitly.
1549 NOTE:
1551 The OLD behavior of a policy is deprecated by definition and may be
1552 removed in a future version of CMake.
1553 CMP0084
1555 New in version 3.14.
1556 The FindQt module does not exist for find_package().
1559 The existence of FindQt means that for Qt upstream to provide package
1561 config files that can be found by find_package(Qt), the consuming
1562 project has to explicitly specify find_package(Qt CONFIG). Removing
1563 this module gives Qt a path forward for exporting its own config files
1564 which can easily be found by consuming projects.
1565 This policy pretends that CMake's internal FindQt module does not exist
1567 for find_package(). If a project really wants to use Qt 3 or 4, it can
1568 call find_package(Qt[34]), include(FindQt), or add FindQt to their
1569 CMAKE_MODULE_PATH.
1570 The OLD behavior of this policy is for FindQt to exist for find_pack‐
1572 age(). The NEW behavior is to pretend that it doesn't exist for
1573 find_package().
1574 This policy was introduced in CMake version 3.14. CMake version 3.22.2
1576 warns when the policy is not set and uses OLD behavior. Use the
1577 cmake_policy() command to set it to OLD or NEW explicitly.
1578 NOTE:
1580 The OLD behavior of a policy is deprecated by definition and may be
1581 removed in a future version of CMake.
1582 CMP0083
1584 New in version 3.14.
1585 To control generation of Position Independent Executable (PIE) or not,
1588 some flags are required at link time.
1589 CMake 3.13 and lower did not add these link flags when POSITION_INDE‐
1591 PENDENT_CODE is set.
1592 The OLD behavior for this policy is to not manage PIE link flags. The
1594 NEW behavior is to add link flags if POSITION_INDEPENDENT_CODE is set:
1595 • Set to TRUE: flags to produce a position independent executable are
1597 passed to the linker step. For example -pie for GCC.
1598 • Set to FALSE: flags not to produce a position independent executable
1600 are passed to the linker step. For example -no-pie for GCC.
1601 • Not set: no flags are passed to the linker step.
1603 Since a given linker may not support PIE flags in all environments in
1605 which it is used, it is the project's responsibility to use the Check‐
1606 PIESupported module to check for support to ensure that the POSI‐
1607 TION_INDEPENDENT_CODE target property for executables will be honored
1608 at link time.
1609 This policy was introduced in CMake version 3.14. Use the cmake_pol‐
1611 icy() command to set it to OLD or NEW explicitly. Unlike most poli‐
1612 cies, CMake version 3.22.2 does not warn when this policy is not set
1613 and simply uses OLD behavior.
1614 NOTE:
1616 Android platform has a special handling of PIE so it is not required
1617 to use the CheckPIESupported module to ensure flags are passed to
1618 the linker.
1619 NOTE:
1621 The OLD behavior of a policy is deprecated by definition and may be
1622 removed in a future version of CMake.
1623 Examples
1625 Behave like CMake 3.13 and do not apply any PIE flags at link stage.
1626 cmake_minimum_required(VERSION 3.13)
1628 project(foo)
1629 # ...
1631 add_executable(foo ...)
1633 set_property(TARGET foo PROPERTY POSITION_INDEPENDENT_CODE TRUE)
1634 Use the CheckPIESupported module to detect whether PIE is supported by
1636 the current linker and environment. Apply PIE flags only if the linker
1637 supports them.
1638 cmake_minimum_required(VERSION 3.14) # CMP0083 NEW
1640 project(foo)
1641 include(CheckPIESupported)
1643 check_pie_supported()
1644 # ...
1646 add_executable(foo ...)
1648 set_property(TARGET foo PROPERTY POSITION_INDEPENDENT_CODE TRUE)
1649 CMP0082
1651 New in version 3.14.
1652 Install rules from add_subdirectory() calls are interleaved with those
1655 in caller.
1656 CMake 3.13 and lower ran the install rules from add_subdirectory() af‐
1658 ter all other install rules, even if add_subdirectory() was called be‐
1659 fore the other install rules. CMake 3.14 and above prefer to inter‐
1660 leave these add_subdirectory() install rules with the others so that
1661 they are run in the order they are declared. This policy provides com‐
1662 patibility for projects that have not been updated to expect the new
1663 behavior.
1664 The OLD behavior for this policy is to run the install rules from
1666 add_subdirectory() after the other install rules. The NEW behavior for
1667 this policy is to run all install rules in the order they are declared.
1668 This policy was introduced in CMake version 3.14. Unlike most poli‐
1670 cies, CMake version 3.22.2 does not warn by default when this policy is
1671 not set and simply uses OLD behavior. See documentation of the
1672 CMAKE_POLICY_WARNING_CMP0082 variable to control the warning.
1673 NOTE:
1675 The OLD behavior of a policy is deprecated by definition and may be
1676 removed in a future version of CMake.
1677
1679 CMP0081
1680 New in version 3.13.
1681 Relative paths not allowed in LINK_DIRECTORIES target property.
1684 CMake 3.12 and lower allowed the LINK_DIRECTORIES directory property to
1686 contain relative paths. The base path for such relative entries is not
1687 well defined. CMake 3.13 and later will issue a FATAL_ERROR if the
1688 LINK_DIRECTORIES target property (which is initialized by the LINK_DI‐
1689 RECTORIES directory property) contains a relative path.
1690 The OLD behavior for this policy is not to warn about relative paths in
1692 the LINK_DIRECTORIES target property. The NEW behavior for this policy
1693 is to issue a FATAL_ERROR if LINK_DIRECTORIES contains a relative path.
1694 This policy was introduced in CMake version 3.13. CMake version 3.22.2
1696 warns when the policy is not set and uses OLD behavior. Use the
1697 cmake_policy() command to set it to OLD or NEW explicitly.
1698 NOTE:
1700 The OLD behavior of a policy is deprecated by definition and may be
1701 removed in a future version of CMake.
1702 CMP0080
1704 New in version 3.13.
1705 BundleUtilities cannot be included at configure time.
1708 The macros provided by BundleUtilities are intended to be invoked at
1710 install time rather than at configure time, because they depend on the
1711 listed targets already existing at the time they are invoked. If they
1712 are invoked at configure time, the targets haven't been built yet, and
1713 the commands will fail.
1714 This policy restricts the inclusion of BundleUtilities to cmake -P
1716 style scripts and install rules. Specifically, it looks for the pres‐
1717 ence of CMAKE_GENERATOR and throws a fatal error if it exists.
1718 The OLD behavior of this policy is to allow BundleUtilities to be in‐
1720 cluded at configure time. The NEW behavior of this policy is to disal‐
1721 low such inclusion.
1722 This policy was introduced in CMake version 3.13. CMake version 3.22.2
1724 warns when the policy is not set and uses OLD behavior. Use the
1725 cmake_policy() command to set it to OLD or NEW explicitly.
1726 NOTE:
1728 The OLD behavior of a policy is deprecated by definition and may be
1729 removed in a future version of CMake.
1730 CMP0079
1732 New in version 3.13.
1733 target_link_libraries() allows use with targets in other directories.
1736 Prior to CMake 3.13 the target_link_libraries() command did not accept
1738 targets not created in the calling directory as its first argument for
1739 calls that update the LINK_LIBRARIES of the target itself. It did ac‐
1740 cidentally accept targets from other directories on calls that only up‐
1741 date the INTERFACE_LINK_LIBRARIES, but would simply add entries to the
1742 property as if the call were made in the original directory. Thus link
1743 interface libraries specified this way were always looked up by genera‐
1744 tors in the scope of the original target rather than in the scope that
1745 called target_link_libraries().
1746 CMake 3.13 now allows the target_link_libraries() command to be called
1748 from any directory to add link dependencies and link interface li‐
1749 braries to targets created in other directories. The entries are added
1750 to LINK_LIBRARIES and INTERFACE_LINK_LIBRARIES using a special (inter‐
1751 nal) suffix to tell the generators to look up the names in the calling
1752 scope rather than the scope that created the target.
1753 This policy provides compatibility with projects that already use tar‐
1755 get_link_libraries() with the INTERFACE keyword on a target in another
1756 directory to add INTERFACE_LINK_LIBRARIES entries to be looked up in
1757 the target's directory. Such projects should be updated to be aware of
1758 the new scoping rules in that case.
1759 The OLD behavior of this policy is to disallow target_link_libraries()
1761 calls naming targets from another directory except in the previously
1762 accidentally allowed case of using the INTERFACE keyword only. The NEW
1763 behavior of this policy is to allow all such calls but use the new
1764 scoping rules.
1765 This policy was introduced in CMake version 3.13. CMake version 3.22.2
1767 warns when the policy is not set and uses OLD behavior. Use the
1768 cmake_policy() command to set it to OLD or NEW explicitly.
1769 NOTE:
1771 The OLD behavior of a policy is deprecated by definition and may be
1772 removed in a future version of CMake.
1773 CMP0078
1775 New in version 3.13.
1776 UseSWIG generates standard target names.
1779 Starting with CMake 3.13, UseSWIG generates now standard target names.
1781 This policy provides compatibility with projects that expect the legacy
1782 behavior.
1783 The OLD behavior for this policy relies on UseSWIG_TARGET_NAME_PREFER‐
1785 ENCE variable that can be used to specify an explicit preference. The
1786 value may be one of:
1787 • LEGACY: legacy strategy is applied. Variable SWIG_MOD‐
1789 ULE_<name>_REAL_NAME must be used to get real target name. This is
1790 the default if not specified.
1791 • STANDARD: target name matches specified name.
1793 This policy was introduced in CMake version 3.13. CMake version 3.22.2
1795 warns when the policy is not set and uses OLD behavior. Use the
1796 cmake_policy() command to set it to OLD or NEW explicitly.
1797 NOTE:
1799 The OLD behavior of a policy is deprecated by definition and may be
1800 removed in a future version of CMake.
1801 CMP0077
1803 New in version 3.13.
1804 option() honors normal variables.
1807 The option() command is typically used to create a cache entry to allow
1809 users to set the option. However, there are cases in which a normal
1810 (non-cached) variable of the same name as the option may be defined by
1811 the project prior to calling the option() command. For example, a
1812 project that embeds another project as a subdirectory may want to
1813 hard-code options of the subproject to build the way it needs.
1814 For historical reasons in CMake 3.12 and below the option() command re‐
1816 moves a normal (non-cached) variable of the same name when:
1817 • a cache entry of the specified name does not exist at all, or
1819 • a cache entry of the specified name exists but has not been given a
1821 type (e.g. via -D<name>=ON on the command line).
1822 In both of these cases (typically on the first run in a new build
1824 tree), the option() command gives the cache entry type BOOL and removes
1825 any normal (non-cached) variable of the same name. In the remaining
1826 case that the cache entry of the specified name already exists and has
1827 a type (typically on later runs in a build tree), the option() command
1828 changes nothing and any normal variable of the same name remains set.
1829 In CMake 3.13 and above the option() command prefers to do nothing when
1831 a normal variable of the given name already exists. It does not create
1832 or update a cache entry or remove the normal variable. The new behav‐
1833 ior is consistent between the first and later runs in a build tree.
1834 This policy provides compatibility with projects that have not been up‐
1835 dated to expect the new behavior.
1836 When the option() command sees a normal variable of the given name:
1838 • The OLD behavior for this policy is to proceed even when a normal
1840 variable of the same name exists. If the cache entry does not al‐
1841 ready exist and have a type then it is created and/or given a type
1842 and the normal variable is removed.
1843 • The NEW behavior for this policy is to do nothing when a normal vari‐
1845 able of the same name exists. The normal variable is not removed.
1846 The cache entry is not created or updated and is ignored if it ex‐
1847 ists.
1848 See CMP0126 for a similar policy for the set(CACHE) command, but note
1850 that there are some differences in NEW behavior between the two poli‐
1851 cies.
1852 This policy was introduced in CMake version 3.13. CMake version 3.22.2
1854 warns when the policy is not set and uses OLD behavior. Use the
1855 cmake_policy() command to set it to OLD or NEW explicitly within a
1856 project. Use the CMAKE_POLICY_DEFAULT_CMP0077 variable to set the pol‐
1857 icy for a third-party project in a subdirectory without modifying it.
1858 NOTE:
1860 The OLD behavior of a policy is deprecated by definition and may be
1861 removed in a future version of CMake.
1862 CMP0076
1864 New in version 3.13.
1865 The target_sources() command converts relative paths to absolute.
1868 In CMake 3.13 and above, the target_sources() command now converts rel‐
1870 ative source file paths to absolute paths in the following cases:
1871 • Source files are added to the target's INTERFACE_SOURCES property.
1873 • The target's SOURCE_DIR property differs from CMAKE_CUR‐
1875 RENT_SOURCE_DIR.
1876 A path that begins with a generator expression is always left unmodi‐
1878 fied.
1879 This policy provides compatibility with projects that have not been up‐
1881 dated to expect this behavior. The OLD behavior for this policy is to
1882 leave all relative source file paths unmodified. The NEW behavior of
1883 this policy is to convert relative paths to absolute according to above
1884 rules.
1885 This policy was introduced in CMake version 3.13. CMake version 3.22.2
1887 warns when the policy is not set and uses OLD behavior. Use the
1888 cmake_policy() command to set it to OLD or NEW explicitly.
1889 NOTE:
1891 The OLD behavior of a policy is deprecated by definition and may be
1892 removed in a future version of CMake.
1893
1895 CMP0075
1896 New in version 3.12.
1897 Include file check macros honor CMAKE_REQUIRED_LIBRARIES.
1900 In CMake 3.12 and above, the
1902 • check_include_file macro in the CheckIncludeFile module, the
1904 • check_include_file_cxx macro in the CheckIncludeFileCXX module, and
1906 the
1907 • check_include_files macro in the CheckIncludeFiles module
1909 now prefer to link the check executable to the libraries listed in the
1911 CMAKE_REQUIRED_LIBRARIES variable. This policy provides compatibility
1912 with projects that have not been updated to expect this behavior.
1913 The OLD behavior for this policy is to ignore CMAKE_REQUIRED_LIBRARIES
1915 in the include file check macros. The NEW behavior of this policy is
1916 to honor CMAKE_REQUIRED_LIBRARIES in the include file check macros.
1917 This policy was introduced in CMake version 3.12. CMake version 3.22.2
1919 warns when the policy is not set and uses OLD behavior. Use the
1920 cmake_policy() command to set it to OLD or NEW explicitly.
1921 NOTE:
1923 The OLD behavior of a policy is deprecated by definition and may be
1924 removed in a future version of CMake.
1925 CMP0074
1927 New in version 3.12.
1928 find_package() uses <PackageName>_ROOT variables.
1931 In CMake 3.12 and above the find_package(<PackageName>) command now
1933 searches prefixes specified by the <PackageName>_ROOT CMake variable
1934 and the <PackageName>_ROOT environment variable. Package roots are
1935 maintained as a stack so nested calls to all find_* commands inside
1936 find modules and config packages also search the roots as prefixes.
1937 This policy provides compatibility with projects that have not been up‐
1938 dated to avoid using <PackageName>_ROOT variables for other purposes.
1939 The OLD behavior for this policy is to ignore <PackageName>_ROOT vari‐
1941 ables. The NEW behavior for this policy is to use <PackageName>_ROOT
1942 variables.
1943 This policy was introduced in CMake version 3.12. CMake version 3.22.2
1945 warns when the policy is not set and uses OLD behavior. Use the
1946 cmake_policy() command to set it to OLD or NEW explicitly.
1947 NOTE:
1949 The OLD behavior of a policy is deprecated by definition and may be
1950 removed in a future version of CMake.
1951 CMP0073
1953 New in version 3.12.
1954 Do not produce legacy _LIB_DEPENDS cache entries.
1957 Ancient CMake versions once used <tgt>_LIB_DEPENDS cache entries to
1959 propagate library link dependencies. This has long been done by other
1960 means, leaving the export_library_dependencies() command as the only
1961 user of these values. That command has long been disallowed by policy
1962 CMP0033, but the <tgt>_LIB_DEPENDS cache entries were left for compati‐
1963 bility with possible non-standard uses by projects.
1964 CMake 3.12 and above now prefer to not produce these cache entries at
1966 all. This policy provides compatibility with projects that have not
1967 been updated to avoid using them.
1968 The OLD behavior for this policy is to set <tgt>_LIB_DEPENDS cache en‐
1970 tries. The NEW behavior for this policy is to not set them.
1971 This policy was introduced in CMake version 3.12. Use the cmake_pol‐
1973 icy() command to set it to OLD or NEW explicitly. Unlike most poli‐
1974 cies, CMake version 3.22.2 does not warn when this policy is not set
1975 and simply uses OLD behavior.
1976 NOTE:
1978 The OLD behavior of a policy is deprecated by definition and may be
1979 removed in a future version of CMake.
1980
1982 CMP0072
1983 New in version 3.11.
1984 FindOpenGL prefers GLVND by default when available.
1987 The FindOpenGL module provides an OpenGL::GL target and an OPENGL_LI‐
1989 BRARIES variable for projects to use for legacy GL interfaces. When
1990 both a legacy GL library (e.g. libGL.so) and GLVND libraries for OpenGL
1991 and GLX (e.g. libOpenGL.so and libGLX.so) are available, the module
1992 must choose between them. It documents an OpenGL_GL_PREFERENCE vari‐
1993 able that can be used to specify an explicit preference. When no such
1994 preference is set, the module must choose a default preference.
1995 CMake 3.11 and above prefer to choose GLVND libraries. This policy
1997 provides compatibility with projects that expect the legacy GL library
1998 to be used.
1999 The OLD behavior for this policy is to set OpenGL_GL_PREFERENCE to
2001 LEGACY. The NEW behavior for this policy is to set OpenGL_GL_PREFER‐
2002 ENCE to GLVND.
2003 This policy was introduced in CMake version 3.11. CMake version 3.22.2
2005 warns when the policy is not set and uses OLD behavior. Use the
2006 cmake_policy() command to set it to OLD or NEW explicitly.
2007 NOTE:
2009 The OLD behavior of a policy is deprecated by definition and may be
2010 removed in a future version of CMake.
2011
2013 CMP0071
2014 New in version 3.10.
2015 Let AUTOMOC and AUTOUIC process GENERATED files.
2018 Since version 3.10, CMake processes regular and GENERATED source files
2020 in AUTOMOC and AUTOUIC. In earlier CMake versions, only regular source
2021 files were processed. GENERATED source files were ignored silently.
2022 This policy affects how source files that are GENERATED get treated in
2024 AUTOMOC and AUTOUIC.
2025 The OLD behavior for this policy is to ignore GENERATED source files in
2027 AUTOMOC and AUTOUIC.
2028 The NEW behavior for this policy is to process GENERATED source files
2030 in AUTOMOC and AUTOUIC just like regular source files.
2031 NOTE:
2033 To silence the CMP0071 warning source files can be excluded from AU‐
2034 TOMOC and AUTOUIC processing by setting the source file properties
2035 SKIP_AUTOMOC, SKIP_AUTOUIC or SKIP_AUTOGEN.
2036 Source skip example:
2038 # ...
2040 set_property(SOURCE /path/to/file1.h PROPERTY SKIP_AUTOMOC ON)
2041 set_property(SOURCE /path/to/file2.h PROPERTY SKIP_AUTOUIC ON)
2042 set_property(SOURCE /path/to/file3.h PROPERTY SKIP_AUTOGEN ON)
2043 # ...
2044 This policy was introduced in CMake version 3.10. CMake version 3.22.2
2046 warns when the policy is not set and uses OLD behavior. Use the
2047 cmake_policy() command to set it to OLD or NEW explicitly.
2048 NOTE:
2050 The OLD behavior of a policy is deprecated by definition and may be
2051 removed in a future version of CMake.
2052 CMP0070
2054 New in version 3.10.
2055 Define file(GENERATE) behavior for relative paths.
2058 CMake 3.10 and newer define that relative paths given to INPUT and OUT‐
2060 PUT arguments of file(GENERATE) are interpreted relative to the current
2061 source and binary directories, respectively. CMake 3.9 and lower did
2062 not define any behavior for relative paths but did not diagnose them
2063 either and accidentally treated them relative to the process working
2064 directory. Policy CMP0070 provides compatibility with projects that
2065 used the old undefined behavior.
2066 This policy affects behavior of relative paths given to file(GENERATE).
2068 The OLD behavior for this policy is to treat the paths relative to the
2069 working directory of CMake. The NEW behavior for this policy is to in‐
2070 terpret relative paths with respect to the current source or binary di‐
2071 rectory of the caller.
2072 This policy was introduced in CMake version 3.10. CMake version 3.22.2
2074 warns when the policy is not set and uses OLD behavior. Use the
2075 cmake_policy() command to set it to OLD or NEW explicitly.
2076 NOTE:
2078 The OLD behavior of a policy is deprecated by definition and may be
2079 removed in a future version of CMake.
2080
2082 CMP0069
2083 New in version 3.9.
2084 INTERPROCEDURAL_OPTIMIZATION is enforced when enabled.
2087 CMake 3.9 and newer prefer to add IPO flags whenever the INTERPROCEDU‐
2089 RAL_OPTIMIZATION target property is enabled and produce an error if
2090 flags are not known to CMake for the current compiler. Since a given
2091 compiler may not support IPO flags in all environments in which it is
2092 used, it is now the project's responsibility to use the CheckIPOSup‐
2093 ported module to check for support before enabling the INTERPROCEDU‐
2094 RAL_OPTIMIZATION target property. This approach allows a project to
2095 conditionally activate IPO when supported. It also allows an end user
2096 to set the CMAKE_INTERPROCEDURAL_OPTIMIZATION variable in an environ‐
2097 ment known to support IPO even if the project does not enable the prop‐
2098 erty.
2099 Since CMake 3.8 and lower only honored INTERPROCEDURAL_OPTIMIZATION for
2101 the Intel compiler on Linux, some projects may unconditionally enable
2102 the target property. Policy CMP0069 provides compatibility with such
2103 projects.
2104 This policy takes effect whenever the IPO property is enabled. The OLD
2106 behavior for this policy is to add IPO flags only for Intel compiler on
2107 Linux. The NEW behavior for this policy is to add IPO flags for the
2108 current compiler or produce an error if CMake does not know the flags.
2109 This policy was introduced in CMake version 3.9. CMake version 3.22.2
2111 warns when the policy is not set and uses OLD behavior. Use the
2112 cmake_policy() command to set it to OLD or NEW explicitly.
2113 NOTE:
2115 The OLD behavior of a policy is deprecated by definition and may be
2116 removed in a future version of CMake.
2117 Examples
2119 Behave like CMake 3.8 and do not apply any IPO flags except for Intel
2120 compiler on Linux:
2121 cmake_minimum_required(VERSION 3.8)
2123 project(foo)
2124 # ...
2126 set_property(TARGET ... PROPERTY INTERPROCEDURAL_OPTIMIZATION TRUE)
2128 Use the CheckIPOSupported module to detect whether IPO is supported by
2130 the current compiler, environment, and CMake version. Produce a fatal
2131 error if support is not available:
2132 cmake_minimum_required(VERSION 3.9) # CMP0069 NEW
2134 project(foo)
2135 include(CheckIPOSupported)
2137 check_ipo_supported()
2138 # ...
2140 set_property(TARGET ... PROPERTY INTERPROCEDURAL_OPTIMIZATION TRUE)
2142 Apply IPO flags only if compiler supports it:
2144 cmake_minimum_required(VERSION 3.9) # CMP0069 NEW
2146 project(foo)
2147 include(CheckIPOSupported)
2149 # ...
2151 check_ipo_supported(RESULT result)
2153 if(result)
2154 set_property(TARGET ... PROPERTY INTERPROCEDURAL_OPTIMIZATION TRUE)
2155 endif()
2156 Apply IPO flags without any checks. This may lead to build errors if
2158 IPO is not supported by the compiler in the current environment. Pro‐
2159 duce an error if CMake does not know IPO flags for the current com‐
2160 piler:
2161 cmake_minimum_required(VERSION 3.9) # CMP0069 NEW
2163 project(foo)
2164 # ...
2166 set_property(TARGET ... PROPERTY INTERPROCEDURAL_OPTIMIZATION TRUE)
2168 CMP0068
2170 New in version 3.9.
2171 RPATH settings on macOS do not affect install_name.
2174 CMake 3.9 and newer remove any effect the following settings may have
2176 on the install_name of a target on macOS:
2177 • BUILD_WITH_INSTALL_RPATH target property
2179 • SKIP_BUILD_RPATH target property
2181 • CMAKE_SKIP_RPATH variable
2183 • CMAKE_SKIP_INSTALL_RPATH variable
2185 Previously, setting BUILD_WITH_INSTALL_RPATH had the effect of setting
2187 both the install_name of a target to INSTALL_NAME_DIR and the RPATH to
2188 INSTALL_RPATH. In CMake 3.9, it only affects setting of RPATH. How‐
2189 ever, if one wants INSTALL_NAME_DIR to apply to the target in the build
2190 tree, one may set BUILD_WITH_INSTALL_NAME_DIR.
2191 If SKIP_BUILD_RPATH, CMAKE_SKIP_RPATH or CMAKE_SKIP_INSTALL_RPATH were
2193 used to strip the directory portion of the install_name of a target,
2194 one may set INSTALL_NAME_DIR="" instead.
2195 The OLD behavior of this policy is to use the RPATH settings for in‐
2197 stall_name on macOS. The NEW behavior of this policy is to ignore the
2198 RPATH settings for install_name on macOS.
2199 This policy was introduced in CMake version 3.9. CMake version 3.22.2
2201 warns when the policy is not set and uses OLD behavior. Use the
2202 cmake_policy() command to set it to OLD or NEW explicitly.
2203 NOTE:
2205 The OLD behavior of a policy is deprecated by definition and may be
2206 removed in a future version of CMake.
2207
2209 CMP0067
2210 New in version 3.8.
2211 Honor language standard in try_compile() source-file signature.
2214 The try_compile() source file signature is intended to allow callers to
2216 check whether they will be able to compile a given source file with the
2217 current toolchain. In order to match compiler behavior, any language
2218 standard mode should match. However, CMake 3.7 and below did not do
2219 this. CMake 3.8 and above prefer to honor the language standard set‐
2220 tings for C, CXX (C++), and CUDA using the values of the variables:
2221 • CMAKE_C_STANDARD
2223 • CMAKE_C_STANDARD_REQUIRED
2225 • CMAKE_C_EXTENSIONS
2227 • CMAKE_CXX_STANDARD
2229 • CMAKE_CXX_STANDARD_REQUIRED
2231 • CMAKE_CXX_EXTENSIONS
2233 • CMAKE_CUDA_STANDARD
2235 • CMAKE_CUDA_STANDARD_REQUIRED
2237 • CMAKE_CUDA_EXTENSIONS
2239 This policy provides compatibility for projects that do not expect the
2241 language standard settings to be used automatically.
2242 The OLD behavior of this policy is to ignore language standard setting
2244 variables when generating the try_compile test project. The NEW behav‐
2245 ior of this policy is to honor language standard setting variables.
2246 This policy was introduced in CMake version 3.8. Unlike most policies,
2248 CMake version 3.22.2 does not warn by default when this policy is not
2249 set and simply uses OLD behavior. See documentation of the CMAKE_POL‐
2250 ICY_WARNING_CMP0067 variable to control the warning.
2251 NOTE:
2253 The OLD behavior of a policy is deprecated by definition and may be
2254 removed in a future version of CMake.
2255
2257 CMP0066
2258 New in version 3.7.
2259 Honor per-config flags in try_compile() source-file signature.
2262 The source file signature of the try_compile() command uses the value
2264 of the CMAKE_<LANG>_FLAGS variable in the test project so that the test
2265 compilation works as it would in the main project. However, CMake 3.6
2266 and below do not also honor config-specific compiler flags such as
2267 those in the CMAKE_<LANG>_FLAGS_DEBUG variable. CMake 3.7 and above
2268 prefer to honor config-specific compiler flags too. This policy pro‐
2269 vides compatibility for projects that do not expect config-specific
2270 compiler flags to be used.
2271 The OLD behavior of this policy is to ignore config-specific flag vari‐
2273 ables like CMAKE_<LANG>_FLAGS_DEBUG and only use CMake's built-in de‐
2274 faults for the current compiler and platform.
2275 The NEW behavior of this policy is to honor config-specific flag vari‐
2277 abldes like CMAKE_<LANG>_FLAGS_DEBUG.
2278 This policy was introduced in CMake version 3.7. Unlike most policies,
2280 CMake version 3.22.2 does not warn by default when this policy is not
2281 set and simply uses OLD behavior. See documentation of the CMAKE_POL‐
2282 ICY_WARNING_CMP0066 variable to control the warning.
2283 NOTE:
2285 The OLD behavior of a policy is deprecated by definition and may be
2286 removed in a future version of CMake.
2287
2289 CMP0065
2290 New in version 3.4.
2291 Do not add flags to export symbols from executables without the EN‐
2294 ABLE_EXPORTS target property.
2295 CMake 3.3 and below, for historical reasons, always linked executables
2297 on some platforms with flags like -rdynamic to export symbols from the
2298 executables for use by any plugins they may load via dlopen. CMake 3.4
2299 and above prefer to do this only for executables that are explicitly
2300 marked with the ENABLE_EXPORTS target property.
2301 The OLD behavior of this policy is to always use the additional link
2303 flags when linking executables regardless of the value of the EN‐
2304 ABLE_EXPORTS target property.
2305 The NEW behavior of this policy is to only use the additional link
2307 flags when linking executables if the ENABLE_EXPORTS target property is
2308 set to True.
2309 This policy was introduced in CMake version 3.4. Unlike most policies,
2311 CMake version 3.22.2 does not warn by default when this policy is not
2312 set and simply uses OLD behavior. See documentation of the CMAKE_POL‐
2313 ICY_WARNING_CMP0065 variable to control the warning.
2314 NOTE:
2316 The OLD behavior of a policy is deprecated by definition and may be
2317 removed in a future version of CMake.
2318 CMP0064
2320 New in version 3.4.
2321 Recognize TEST as a operator for the if() command.
2324 The TEST operator was added to the if() command to determine if a given
2326 test name was created by the add_test() command.
2327 The OLD behavior for this policy is to ignore the TEST operator. The
2329 NEW behavior is to interpret the TEST operator.
2330 This policy was introduced in CMake version 3.4. CMake version 3.22.2
2332 warns when the policy is not set and uses OLD behavior. Use the
2333 cmake_policy() command to set it to OLD or NEW explicitly.
2334 NOTE:
2336 The OLD behavior of a policy is deprecated by definition and may be
2337 removed in a future version of CMake.
2338
2340 CMP0063
2341 New in version 3.3.
2342 Honor visibility properties for all target types.
2345 The <LANG>_VISIBILITY_PRESET and VISIBILITY_INLINES_HIDDEN target prop‐
2347 erties affect visibility of symbols during dynamic linking. When first
2348 introduced these properties affected compilation of sources only in
2349 shared libraries, module libraries, and executables with the ENABLE_EX‐
2350 PORTS property set. This was sufficient for the basic use cases of
2351 shared libraries and executables with plugins. However, some sources
2352 may be compiled as part of static libraries or object libraries and
2353 then linked into a shared library later. CMake 3.3 and above prefer to
2354 honor these properties for sources compiled in all target types. This
2355 policy preserves compatibility for projects expecting the properties to
2356 work only for some target types.
2357 The OLD behavior for this policy is to ignore the visibility properties
2359 for static libraries, object libraries, and executables without ex‐
2360 ports. The NEW behavior for this policy is to honor the visibility
2361 properties for all target types.
2362 This policy was introduced in CMake version 3.3. CMake version 3.22.2
2364 warns when the policy is not set and uses OLD behavior. Use the
2365 cmake_policy() command to set it to OLD or NEW explicitly.
2366 NOTE:
2368 The OLD behavior of a policy is deprecated by definition and may be
2369 removed in a future version of CMake.
2370 CMP0062
2372 New in version 3.3.
2373 Disallow install() of export() result.
2376 The export() command generates a file containing Imported Targets,
2378 which is suitable for use from the build directory. It is not suitable
2379 for installation because it contains absolute paths to buildsystem lo‐
2380 cations, and is particular to a single build configuration.
2381 The install(EXPORT) generates and installs files which contain Imported
2383 Targets. These files are generated with relative paths (unless the
2384 user specifies absolute paths), and are designed for multi-configura‐
2385 tion use. See Creating Packages for more.
2386 CMake 3.3 no longer allows the use of the install(FILES) command with
2388 the result of the export() command.
2389 The OLD behavior for this policy is to allow installing the result of
2391 an export() command. The NEW behavior for this policy is not to allow
2392 installing the result of an export() command.
2393 This policy was introduced in CMake version 3.3. CMake version 3.22.2
2395 warns when the policy is not set and uses OLD behavior. Use the
2396 cmake_policy() command to set it to OLD or NEW explicitly.
2397 NOTE:
2399 The OLD behavior of a policy is deprecated by definition and may be
2400 removed in a future version of CMake.
2401 CMP0061
2403 New in version 3.3.
2404 CTest does not by default tell make to ignore errors (-i).
2407 The ctest_build() and build_command() commands no longer generate build
2409 commands for Makefile Generators with the -i option. Previously this
2410 was done to help build as much of tested projects as possible. How‐
2411 ever, this behavior is not consistent with other generators and also
2412 causes the return code of the make tool to be meaningless.
2413 Of course users may still add this option manually by setting
2415 CTEST_BUILD_COMMAND or the MAKECOMMAND cache entry. See the CTest
2416 Build Step MakeCommand setting documentation for their effects.
2417 The OLD behavior for this policy is to add -i to make calls in CTest.
2419 The NEW behavior for this policy is to not add -i.
2420 This policy was introduced in CMake version 3.3. Unlike most policies,
2422 CMake version 3.22.2 does not warn when this policy is not set and sim‐
2423 ply uses OLD behavior.
2424 NOTE:
2426 The OLD behavior of a policy is deprecated by definition and may be
2427 removed in a future version of CMake.
2428 CMP0060
2430 New in version 3.3.
2431 Link libraries by full path even in implicit directories.
2434 Policy CMP0003 was introduced with the intention of always linking li‐
2436 brary files by full path when a full path is given to the tar‐
2437 get_link_libraries() command. However, on some platforms (e.g. HP-UX)
2438 the compiler front-end adds alternative library search paths for the
2439 current architecture (e.g. /usr/lib/<arch> has alternatives to li‐
2440 braries in /usr/lib for the current architecture). On such platforms
2441 the find_library() may find a library such as /usr/lib/libfoo.so that
2442 does not belong to the current architecture.
2443 Prior to policy CMP0003 projects would still build in such cases be‐
2445 cause the incorrect library path would be converted to -lfoo on the
2446 link line and the linker would find the proper library in the arch-spe‐
2447 cific search path provided by the compiler front-end implicitly. At
2448 the time we chose to remain compatible with such projects by always
2449 converting library files found in implicit link directories to -lfoo
2450 flags to ask the linker to search for them. This approach allowed ex‐
2451 isting projects to continue to build while still linking to libraries
2452 outside implicit link directories via full path (such as those in the
2453 build tree).
2454 CMake does allow projects to override this behavior by using an IM‐
2456 PORTED library target with its IMPORTED_LOCATION property set to the
2457 desired full path to a library file. In fact, many Find Modules are
2458 learning to provide Imported Targets instead of just the traditional
2459 Foo_LIBRARIES variable listing library files. However, this makes the
2460 link line generated for a library found by a Find Module depend on
2461 whether it is linked through an imported target or not, which is incon‐
2462 sistent. Furthermore, this behavior has been a source of confusion be‐
2463 cause the generated link line for a library file depends on its loca‐
2464 tion. It is also problematic for projects trying to link statically
2465 because flags like -Wl,-Bstatic -lfoo -Wl,-Bdynamic may be used to help
2466 the linker select libfoo.a instead of libfoo.so but then leak dynamic
2467 linking to following libraries. (See the LINK_SEARCH_END_STATIC target
2468 property for a solution typically used for that problem.)
2469 When the special case for libraries in implicit link directories was
2471 first introduced the list of implicit link directories was simply
2472 hard-coded (e.g. /lib, /usr/lib, and a few others). Since that time,
2473 CMake has learned to detect the implicit link directories used by the
2474 compiler front-end. If necessary, the find_library() command could be
2475 taught to use this information to help find libraries of the proper ar‐
2476 chitecture.
2477 For these reasons, CMake 3.3 and above prefer to drop the special case
2479 and link libraries by full path even when they are in implicit link di‐
2480 rectories. Policy CMP0060 provides compatibility for existing
2481 projects.
2482 The OLD behavior for this policy is to ask the linker to search for li‐
2484 braries whose full paths are known to be in implicit link directories.
2485 The NEW behavior for this policy is to link libraries by full path even
2486 if they are in implicit link directories.
2487 This policy was introduced in CMake version 3.3. Unlike most policies,
2489 CMake version 3.22.2 does not warn by default when this policy is not
2490 set and simply uses OLD behavior. See documentation of the CMAKE_POL‐
2491 ICY_WARNING_CMP0060 variable to control the warning.
2492 NOTE:
2494 The OLD behavior of a policy is deprecated by definition and may be
2495 removed in a future version of CMake.
2496 CMP0059
2498 New in version 3.3.
2499 Do not treat DEFINITIONS as a built-in directory property.
2502 CMake 3.3 and above no longer make a list of definitions available
2504 through the DEFINITIONS directory property. The COMPILE_DEFINITIONS
2505 directory property may be used instead.
2506 The OLD behavior for this policy is to provide the list of flags given
2508 so far to the add_definitions() command. The NEW behavior is to behave
2509 as a normal user-defined directory property.
2510 This policy was introduced in CMake version 3.3. CMake version 3.22.2
2512 warns when the policy is not set and uses OLD behavior. Use the
2513 cmake_policy() command to set it to OLD or NEW explicitly.
2514 NOTE:
2516 The OLD behavior of a policy is deprecated by definition and may be
2517 removed in a future version of CMake.
2518 CMP0058
2520 New in version 3.3.
2521 Ninja requires custom command byproducts to be explicit.
2524 When an intermediate file generated during the build is consumed by an
2526 expensive operation or a large tree of dependents, one may reduce the
2527 work needed for an incremental rebuild by updating the file timestamp
2528 only when its content changes. With this approach the generation rule
2529 must have a separate output file that is always updated with a new
2530 timestamp that is newer than any dependencies of the rule so that the
2531 build tool re-runs the rule only when the input changes. We refer to
2532 the separate output file as a rule's witness and the generated file as
2533 a rule's byproduct.
2534 Byproducts may not be listed as outputs because their timestamps are
2536 allowed to be older than the inputs. No build tools (like make) that
2537 existed when CMake was designed have a way to express byproducts.
2538 Therefore CMake versions prior to 3.2 had no way to specify them.
2539 Projects typically left byproducts undeclared in the rules that gener‐
2540 ate them. For example:
2541 add_custom_command(
2543 OUTPUT witness.txt
2544 COMMAND ${CMAKE_COMMAND} -E copy_if_different
2545 ${CMAKE_CURRENT_SOURCE_DIR}/input.txt
2546 byproduct.txt # timestamp may not change
2547 COMMAND ${CMAKE_COMMAND} -E touch witness.txt
2548 DEPENDS ${CMAKE_CURRENT_SOURCE_DIR}/input.txt
2549 )
2550 add_custom_target(Provider DEPENDS witness.txt)
2551 add_custom_command(
2552 OUTPUT generated.c
2553 COMMAND expensive-task -i byproduct.txt -o generated.c
2554 DEPENDS ${CMAKE_CURRENT_BINARY_DIR}/byproduct.txt
2555 )
2556 add_library(Consumer generated.c)
2557 add_dependencies(Consumer Provider)
2558 This works well for all generators except Ninja. The Ninja build tool
2560 sees a rule listing byproduct.txt as a dependency and no rule listing
2561 it as an output. Ninja then complains that there is no way to satisfy
2562 the dependency and stops building even though there are order-only de‐
2563 pendencies that ensure byproduct.txt will exist before its consumers
2564 need it. See discussion of this problem in Ninja Issue 760 for further
2565 details on why Ninja works this way.
2566 Instead of leaving byproducts undeclared in the rules that generate
2568 them, Ninja expects byproducts to be listed along with other outputs.
2569 Such rules may be marked with a restat option that tells Ninja to check
2570 the timestamps of outputs after the rules run. This prevents byprod‐
2571 ucts whose timestamps do not change from causing their dependents to
2572 re-build unnecessarily.
2573 Since the above approach does not tell CMake what custom command gener‐
2575 ates byproduct.txt, the Ninja generator does not have enough informa‐
2576 tion to add the byproduct as an output of any rule. CMake 2.8.12 and
2577 above work around this problem and allow projects using the above ap‐
2578 proach to build by generating phony build rules to tell Ninja to toler‐
2579 ate such missing files. However, this workaround prevents Ninja from
2580 diagnosing a dependency that is really missing. It also works poorly
2581 in in-source builds where every custom command dependency, even on
2582 source files, needs to be treated this way because CMake does not have
2583 enough information to know which files are generated as byproducts of
2584 custom commands.
2585 CMake 3.2 introduced the BYPRODUCTS option to the add_custom_command()
2587 and add_custom_target() commands. This option allows byproducts to be
2588 specified explicitly:
2589 add_custom_command(
2591 OUTPUT witness.txt
2592 BYPRODUCTS byproduct.txt # explicit byproduct specification
2593 COMMAND ${CMAKE_COMMAND} -E copy_if_different
2594 ${CMAKE_CURRENT_SOURCE_DIR}/input.txt
2595 byproduct.txt # timestamp may not change
2596 ...
2597 The BYPRODUCTS option is used by the Ninja generator to list byproducts
2599 among the outputs of the custom commands that generate them, and is ig‐
2600 nored by other generators.
2601 CMake 3.3 and above prefer to require projects to specify custom com‐
2603 mand byproducts explicitly so that it can avoid using the phony rule
2604 workaround altogether. Policy CMP0058 was introduced to provide com‐
2605 patibility with existing projects that still need the workaround.
2606 This policy has no effect on generators other than Ninja. The OLD be‐
2608 havior for this policy is to generate Ninja phony rules for unknown de‐
2609 pendencies in the build tree. The NEW behavior for this policy is to
2610 not generate these and instead require projects to specify custom com‐
2611 mand BYPRODUCTS explicitly.
2612 This policy was introduced in CMake version 3.3. CMake version 3.22.2
2614 warns when it sees unknown dependencies in out-of-source build trees if
2615 the policy is not set and then uses OLD behavior. Use the cmake_pol‐
2616 icy() command to set the policy to OLD or NEW explicitly. The policy
2617 setting must be in scope at the end of the top-level CMakeLists.txt
2618 file of the project and has global effect.
2619 NOTE:
2621 The OLD behavior of a policy is deprecated by definition and may be
2622 removed in a future version of CMake.
2623 CMP0057
2625 New in version 3.3.
2626 Support new if() IN_LIST operator.
2629 CMake 3.3 adds support for the new IN_LIST operator.
2631 The OLD behavior for this policy is to ignore the IN_LIST operator.
2633 The NEW behavior is to interpret the IN_LIST operator.
2634 This policy was introduced in CMake version 3.3. CMake version 3.22.2
2636 warns when the policy is not set and uses OLD behavior. Use the
2637 cmake_policy() command to set it to OLD or NEW explicitly.
2638 NOTE:
2640 The OLD behavior of a policy is deprecated by definition and may be
2641 removed in a future version of CMake.
2642
2644 CMP0056
2645 New in version 3.2.
2646 Honor link flags in try_compile() source-file signature.
2649 The try_compile() command source-file signature generates a CMake‐
2651 Lists.txt file to build the source file into an executable. In order
2652 to compile the source the same way as it might be compiled by the call‐
2653 ing project, the generated project sets the value of the
2654 CMAKE_<LANG>_FLAGS variable to that in the calling project. The value
2655 of the CMAKE_EXE_LINKER_FLAGS variable may be needed in some cases too,
2656 but CMake 3.1 and lower did not set it in the generated project. CMake
2657 3.2 and above prefer to set it so that linker flags are honored as well
2658 as compiler flags. This policy provides compatibility with the pre-3.2
2659 behavior.
2660 The OLD behavior for this policy is to not set the value of the
2662 CMAKE_EXE_LINKER_FLAGS variable in the generated test project. The NEW
2663 behavior for this policy is to set the value of the
2664 CMAKE_EXE_LINKER_FLAGS variable in the test project to the same as it
2665 is in the calling project.
2666 If the project code does not set the policy explicitly, users may set
2668 it on the command line by defining the CMAKE_POLICY_DEFAULT_CMP0056
2669 variable in the cache.
2670 This policy was introduced in CMake version 3.2. Unlike most policies,
2672 CMake version 3.22.2 does not warn by default when this policy is not
2673 set and simply uses OLD behavior. See documentation of the CMAKE_POL‐
2674 ICY_WARNING_CMP0056 variable to control the warning.
2675 NOTE:
2677 The OLD behavior of a policy is deprecated by definition and may be
2678 removed in a future version of CMake.
2679 CMP0055
2681 New in version 3.2.
2682 Strict checking for the break() command.
2685 CMake 3.1 and lower allowed calls to the break() command outside of a
2687 loop context and also ignored any given arguments. This was undefined
2688 behavior.
2689 The OLD behavior for this policy is to allow break() to be placed out‐
2691 side of loop contexts and ignores any arguments. The NEW behavior for
2692 this policy is to issue an error if a misplaced break or any arguments
2693 are found.
2694 This policy was introduced in CMake version 3.2. CMake version 3.22.2
2696 warns when the policy is not set and uses OLD behavior. Use the
2697 cmake_policy() command to set it to OLD or NEW explicitly.
2698 NOTE:
2700 The OLD behavior of a policy is deprecated by definition and may be
2701 removed in a future version of CMake.
2702
2704 CMP0054
2705 New in version 3.1.
2706 Only interpret if() arguments as variables or keywords when unquoted.
2709 CMake 3.1 and above no longer implicitly dereference variables or in‐
2711 terpret keywords in an if() command argument when it is a Quoted Argu‐
2712 ment or a Bracket Argument.
2713 The OLD behavior for this policy is to dereference variables and inter‐
2715 pret keywords even if they are quoted or bracketed. The NEW behavior
2716 is to not dereference variables or interpret keywords that have been
2717 quoted or bracketed.
2718 Given the following partial example:
2720 set(A E)
2722 set(E "")
2723 if("${A}" STREQUAL "")
2725 message("Result is TRUE before CMake 3.1 or when CMP0054 is OLD")
2726 else()
2727 message("Result is FALSE in CMake 3.1 and above if CMP0054 is NEW")
2728 endif()
2729 After explicit expansion of variables this gives:
2731 if("E" STREQUAL "")
2733 With the policy set to OLD implicit expansion reduces this semantically
2735 to:
2736 if("" STREQUAL "")
2738 With the policy set to NEW the quoted arguments will not be further
2740 dereferenced:
2741 if("E" STREQUAL "")
2743 This policy was introduced in CMake version 3.1. CMake version 3.22.2
2745 warns when the policy is not set and uses OLD behavior. Use the
2746 cmake_policy() command to set it to OLD or NEW explicitly.
2747 NOTE:
2749 The OLD behavior of a policy is deprecated by definition and may be
2750 removed in a future version of CMake.
2751 CMP0053
2753 New in version 3.1.
2754 Simplify variable reference and escape sequence evaluation.
2757 CMake 3.1 introduced a much faster implementation of evaluation of the
2759 Variable References and Escape Sequences documented in the cmake-lan‐
2760 guage(7) manual. While the behavior is identical to the legacy imple‐
2761 mentation in most cases, some corner cases were cleaned up to simplify
2762 the behavior. Specifically:
2763 • Expansion of @VAR@ reference syntax defined by the configure_file()
2765 and string(CONFIGURE) commands is no longer performed in other con‐
2766 texts.
2767 • Literal ${VAR} reference syntax may contain only alphanumeric charac‐
2769 ters (A-Z, a-z, 0-9) and the characters _, ., /, -, and +. Note that
2770 $ is technically allowed in the NEW behavior, but is invalid for OLD
2771 behavior. This is due to an oversight during the implementation of
2772 CMP0053 and its use as a literal variable reference is discouraged
2773 for this reason. Variables with other characters in their name may
2774 still be referenced indirectly, e.g.
2775 set(varname "otherwise & disallowed $ characters")
2777 message("${${varname}}")
2778 • The setting of policy CMP0010 is not considered, so improper variable
2780 reference syntax is always an error.
2781 • More characters are allowed to be escaped in variable names. Previ‐
2783 ously, only ()#" \@^ were valid characters to escape. Now any non-al‐
2784 phanumeric, non-semicolon, non-NUL character may be escaped following
2785 the escape_identity production in the Escape Sequences section of the
2786 cmake-language(7) manual.
2787 The OLD behavior for this policy is to honor the legacy behavior for
2789 variable references and escape sequences. The NEW behavior is to use
2790 the simpler variable expansion and escape sequence evaluation rules.
2791 This policy was introduced in CMake version 3.1. CMake version 3.22.2
2793 warns when the policy is not set and uses OLD behavior. Use the
2794 cmake_policy() command to set it to OLD or NEW explicitly.
2795 NOTE:
2797 The OLD behavior of a policy is deprecated by definition and may be
2798 removed in a future version of CMake.
2799 CMP0052
2801 New in version 3.1.
2802 Reject source and build dirs in installed INTERFACE_INCLUDE_DIRECTO‐
2805 RIES.
2806 CMake 3.0 and lower allowed subdirectories of the source directory or
2808 build directory to be in the INTERFACE_INCLUDE_DIRECTORIES of installed
2809 and exported targets, if the directory was also a subdirectory of the
2810 installation prefix. This makes the installation depend on the exis‐
2811 tence of the source dir or binary dir, and the installation will be
2812 broken if either are removed after installation.
2813 See Include Directories and Usage Requirements for more on specifying
2815 include directories for targets.
2816 The OLD behavior for this policy is to export the content of the INTER‐
2818 FACE_INCLUDE_DIRECTORIES with the source or binary directory. The NEW
2819 behavior for this policy is to issue an error if such a directory is
2820 used.
2821 This policy was introduced in CMake version 3.1. CMake version 3.22.2
2823 warns when the policy is not set and uses OLD behavior. Use the
2824 cmake_policy() command to set it to OLD or NEW explicitly.
2825 NOTE:
2827 The OLD behavior of a policy is deprecated by definition and may be
2828 removed in a future version of CMake.
2829 CMP0051
2831 New in version 3.1.
2832 List TARGET_OBJECTS in SOURCES target property.
2835 CMake 3.0 and lower did not include the TARGET_OBJECTS generator ex‐
2837 pression when returning the SOURCES target property.
2838 Configure-time CMake code is not able to handle generator expressions.
2840 If using the SOURCES target property at configure time, it may be nec‐
2841 essary to first remove generator expressions using the
2842 string(GENEX_STRIP) command. Generate-time CMake code such as
2843 file(GENERATE) can handle the content without stripping.
2844 The OLD behavior for this policy is to omit TARGET_OBJECTS expressions
2846 from the SOURCES target property. The NEW behavior for this policy is
2847 to include TARGET_OBJECTS expressions in the output.
2848 This policy was introduced in CMake version 3.1. CMake version 3.22.2
2850 warns when the policy is not set and uses OLD behavior. Use the
2851 cmake_policy() command to set it to OLD or NEW explicitly.
2852 NOTE:
2854 The OLD behavior of a policy is deprecated by definition and may be
2855 removed in a future version of CMake.
2856
2858 CMP0050
2859 Disallow add_custom_command SOURCE signatures.
2860 CMake 2.8.12 and lower allowed a signature for add_custom_command()
2862 which specified an input to a command. This was undocumented behavior.
2863 Modern use of CMake associates custom commands with their output,
2864 rather than their input.
2865 The OLD behavior for this policy is to allow the use of add_custom_com‐
2867 mand() SOURCE signatures. The NEW behavior for this policy is to issue
2868 an error if such a signature is used.
2869 This policy was introduced in CMake version 3.0. CMake version 3.22.2
2871 warns when the policy is not set and uses OLD behavior. Use the
2872 cmake_policy() command to set it to OLD or NEW explicitly.
2873 NOTE:
2875 The OLD behavior of a policy is deprecated by definition and may be
2876 removed in a future version of CMake.
2877 CMP0049
2879 Do not expand variables in target source entries.
2880 CMake 2.8.12 and lower performed an extra layer of variable expansion
2882 when evaluating source file names:
2883 set(a_source foo.c)
2885 add_executable(foo \${a_source})
2886 This was undocumented behavior.
2888 The OLD behavior for this policy is to expand such variables when pro‐
2890 cessing the target sources. The NEW behavior for this policy is to is‐
2891 sue an error if such variables need to be expanded.
2892 This policy was introduced in CMake version 3.0. CMake version 3.22.2
2894 warns when the policy is not set and uses OLD behavior. Use the
2895 cmake_policy() command to set it to OLD or NEW explicitly.
2896 NOTE:
2898 The OLD behavior of a policy is deprecated by definition and may be
2899 removed in a future version of CMake.
2900 CMP0048
2902 The project() command manages VERSION variables.
2903 CMake version 3.0 introduced the VERSION option of the project() com‐
2905 mand to specify a project version as well as the name. In order to
2906 keep PROJECT_VERSION and related variables consistent with variable
2907 PROJECT_NAME it is necessary to set the VERSION variables to the empty
2908 string when no VERSION is given to project(). However, this can change
2909 behavior for existing projects that set VERSION variables themselves
2910 since project() may now clear them. This policy controls the behavior
2911 for compatibility with such projects.
2912 The OLD behavior for this policy is to leave VERSION variables un‐
2914 touched. The NEW behavior for this policy is to set VERSION as docu‐
2915 mented by the project() command.
2916 This policy was introduced in CMake version 3.0. CMake version 3.22.2
2918 warns when the policy is not set and uses OLD behavior. Use the
2919 cmake_policy() command to set it to OLD or NEW explicitly.
2920 NOTE:
2922 The OLD behavior of a policy is deprecated by definition and may be
2923 removed in a future version of CMake.
2924 CMP0047
2926 Use QCC compiler id for the qcc drivers on QNX.
2927 CMake 3.0 and above recognize that the QNX qcc compiler driver is dif‐
2929 ferent from the GNU compiler. CMake now prefers to present this to
2930 projects by setting the CMAKE_<LANG>_COMPILER_ID variable to QCC in‐
2931 stead of GNU. However, existing projects may assume the compiler id
2932 for QNX qcc is just GNU as it was in CMake versions prior to 3.0.
2933 Therefore this policy determines for QNX qcc which compiler id to re‐
2934 port in the CMAKE_<LANG>_COMPILER_ID variable after language <LANG> is
2935 enabled by the project() or enable_language() command. The policy must
2936 be set prior to the invocation of either command.
2937 The OLD behavior for this policy is to use the GNU compiler id for the
2939 qcc and QCC compiler drivers. The NEW behavior for this policy is to
2940 use the QCC compiler id for those drivers.
2941 This policy was introduced in CMake version 3.0. Use the cmake_pol‐
2943 icy() command to set this policy to OLD or NEW explicitly. Unlike most
2944 policies, CMake version 3.22.2 does not warn by default when this pol‐
2945 icy is not set and simply uses OLD behavior. See documentation of the
2946 CMAKE_POLICY_WARNING_CMP0047 variable to control the warning.
2947 NOTE:
2949 The OLD behavior of a policy is deprecated by definition and may be
2950 removed in a future version of CMake.
2951 CMP0046
2953 Error on non-existent dependency in add_dependencies.
2954 CMake 2.8.12 and lower silently ignored non-existent dependencies
2956 listed in the add_dependencies() command.
2957 The OLD behavior for this policy is to silently ignore non-existent de‐
2959 pendencies. The NEW behavior for this policy is to report an error if
2960 non-existent dependencies are listed in the add_dependencies() command.
2961 This policy was introduced in CMake version 3.0. CMake version 3.22.2
2963 warns when the policy is not set and uses OLD behavior. Use the
2964 cmake_policy() command to set it to OLD or NEW explicitly.
2965 NOTE:
2967 The OLD behavior of a policy is deprecated by definition and may be
2968 removed in a future version of CMake.
2969 CMP0045
2971 Error on non-existent target in get_target_property.
2972 In CMake 2.8.12 and lower, the get_target_property() command accepted a
2974 non-existent target argument without issuing any error or warning. The
2975 result variable is set to a -NOTFOUND value.
2976 The OLD behavior for this policy is to issue no warning and set the re‐
2978 sult variable to a -NOTFOUND value. The NEW behavior for this policy
2979 is to issue a FATAL_ERROR if the command is called with a non-existent
2980 target.
2981 This policy was introduced in CMake version 3.0. CMake version 3.22.2
2983 warns when the policy is not set and uses OLD behavior. Use the
2984 cmake_policy() command to set it to OLD or NEW explicitly.
2985 NOTE:
2987 The OLD behavior of a policy is deprecated by definition and may be
2988 removed in a future version of CMake.
2989 CMP0044
2991 Case sensitive <LANG>_COMPILER_ID generator expressions
2992 CMake 2.8.12 introduced the <LANG>_COMPILER_ID generator expressions to
2994 allow comparison of the CMAKE_<LANG>_COMPILER_ID with a test value.
2995 The possible valid values are lowercase, but the comparison with the
2996 test value was performed case-insensitively.
2997 The OLD behavior for this policy is to perform a case-insensitive com‐
2999 parison with the value in the <LANG>_COMPILER_ID expression. The NEW
3000 behavior for this policy is to perform a case-sensitive comparison with
3001 the value in the <LANG>_COMPILER_ID expression.
3002 This policy was introduced in CMake version 3.0. CMake version 3.22.2
3004 warns when the policy is not set and uses OLD behavior. Use the
3005 cmake_policy() command to set it to OLD or NEW explicitly.
3006 NOTE:
3008 The OLD behavior of a policy is deprecated by definition and may be
3009 removed in a future version of CMake.
3010 CMP0043
3012 Ignore COMPILE_DEFINITIONS_<Config> properties
3013 CMake 2.8.12 and lower allowed setting the COMPILE_DEFINITIONS_<CONFIG>
3015 target property and COMPILE_DEFINITIONS_<CONFIG> directory property to
3016 apply configuration-specific compile definitions.
3017 Since CMake 2.8.10, the COMPILE_DEFINITIONS property has supported gen‐
3019 erator expressions for setting configuration-dependent content. The
3020 continued existence of the suffixed variables is redundant, and causes
3021 a maintenance burden. Population of the COMPILE_DEFINITIONS_DEBUG
3022 property may be replaced with a population of COMPILE_DEFINITIONS di‐
3023 rectly or via target_compile_definitions():
3024 # Old Interfaces:
3026 set_property(TARGET tgt APPEND PROPERTY
3027 COMPILE_DEFINITIONS_DEBUG DEBUG_MODE
3028 )
3029 set_property(DIRECTORY APPEND PROPERTY
3030 COMPILE_DEFINITIONS_DEBUG DIR_DEBUG_MODE
3031 )
3032 # New Interfaces:
3034 set_property(TARGET tgt APPEND PROPERTY
3035 COMPILE_DEFINITIONS $<$<CONFIG:Debug>:DEBUG_MODE>
3036 )
3037 target_compile_definitions(tgt PRIVATE $<$<CONFIG:Debug>:DEBUG_MODE>)
3038 set_property(DIRECTORY APPEND PROPERTY
3039 COMPILE_DEFINITIONS $<$<CONFIG:Debug>:DIR_DEBUG_MODE>
3040 )
3041 The OLD behavior for this policy is to consume the content of the suf‐
3043 fixed COMPILE_DEFINITIONS_<CONFIG> target property when generating the
3044 compilation command. The NEW behavior for this policy is to ignore the
3045 content of the COMPILE_DEFINITIONS_<CONFIG> target property .
3046 This policy was introduced in CMake version 3.0. CMake version 3.22.2
3048 warns when the policy is not set and uses OLD behavior. Use the
3049 cmake_policy() command to set it to OLD or NEW explicitly.
3050 NOTE:
3052 The OLD behavior of a policy is deprecated by definition and may be
3053 removed in a future version of CMake.
3054 CMP0042
3056 MACOSX_RPATH is enabled by default.
3057 CMake 2.8.12 and newer has support for using @rpath in a target's in‐
3059 stall name. This was enabled by setting the target property MA‐
3060 COSX_RPATH. The @rpath in an install name is a more flexible and pow‐
3061 erful mechanism than @executable_path or @loader_path for locating
3062 shared libraries.
3063 CMake 3.0 and later prefer this property to be ON by default. Projects
3065 wanting @rpath in a target's install name may remove any setting of the
3066 INSTALL_NAME_DIR and CMAKE_INSTALL_NAME_DIR variables.
3067 This policy was introduced in CMake version 3.0. CMake version 3.22.2
3069 warns when the policy is not set and uses OLD behavior. Use the
3070 cmake_policy() command to set it to OLD or NEW explicitly.
3071 NOTE:
3073 The OLD behavior of a policy is deprecated by definition and may be
3074 removed in a future version of CMake.
3075 CMP0041
3077 Error on relative include with generator expression.
3078 Diagnostics in CMake 2.8.12 and lower silently ignored an entry in the
3080 INTERFACE_INCLUDE_DIRECTORIES of a target if it contained a generator
3081 expression at any position.
3082 The path entries in that target property should not be relative.
3084 High-level API should ensure that by adding either a source directory
3085 or a install directory prefix, as appropriate.
3086 As an additional diagnostic, the INTERFACE_INCLUDE_DIRECTORIES gener‐
3088 ated on an IMPORTED target for the install location should not contain
3089 paths in the source directory or the build directory.
3090 The OLD behavior for this policy is to ignore relative path entries if
3092 they contain a generator expression. The NEW behavior for this policy
3093 is to report an error if a generator expression appears in another lo‐
3094 cation and the path is relative.
3095 This policy was introduced in CMake version 3.0. CMake version 3.22.2
3097 warns when the policy is not set and uses OLD behavior. Use the
3098 cmake_policy() command to set it to OLD or NEW explicitly.
3099 NOTE:
3101 The OLD behavior of a policy is deprecated by definition and may be
3102 removed in a future version of CMake.
3103 CMP0040
3105 The target in the TARGET signature of add_custom_command() must exist
3106 and must be defined in the current directory.
3107 CMake 2.8.12 and lower silently ignored a custom command created with
3109 the TARGET signature of add_custom_command() if the target is unknown
3110 or was defined outside the current directory.
3111 The OLD behavior for this policy is to ignore custom commands for un‐
3113 known targets. The NEW behavior for this policy is to report an error
3114 if the target referenced in add_custom_command() is unknown or was de‐
3115 fined outside the current directory.
3116 This policy was introduced in CMake version 3.0. CMake version 3.22.2
3118 warns when the policy is not set and uses OLD behavior. Use the
3119 cmake_policy() command to set it to OLD or NEW explicitly.
3120 NOTE:
3122 The OLD behavior of a policy is deprecated by definition and may be
3123 removed in a future version of CMake.
3124 CMP0039
3126 Utility targets may not have link dependencies.
3127 CMake 2.8.12 and lower allowed using utility targets in the left hand
3129 side position of the target_link_libraries() command. This is an indi‐
3130 cator of a bug in user code.
3131 The OLD behavior for this policy is to ignore attempts to set the link
3133 libraries of utility targets. The NEW behavior for this policy is to
3134 report an error if an attempt is made to set the link libraries of a
3135 utility target.
3136 This policy was introduced in CMake version 3.0. CMake version 3.22.2
3138 warns when the policy is not set and uses OLD behavior. Use the
3139 cmake_policy() command to set it to OLD or NEW explicitly.
3140 NOTE:
3142 The OLD behavior of a policy is deprecated by definition and may be
3143 removed in a future version of CMake.
3144 CMP0038
3146 Targets may not link directly to themselves.
3147 CMake 2.8.12 and lower allowed a build target to link to itself di‐
3149 rectly with a target_link_libraries() call. This is an indicator of a
3150 bug in user code.
3151 The OLD behavior for this policy is to ignore targets which list them‐
3153 selves in their own link implementation. The NEW behavior for this
3154 policy is to report an error if a target attempts to link to itself.
3155 This policy was introduced in CMake version 3.0. CMake version 3.22.2
3157 warns when the policy is not set and uses OLD behavior. Use the
3158 cmake_policy() command to set it to OLD or NEW explicitly.
3159 NOTE:
3161 The OLD behavior of a policy is deprecated by definition and may be
3162 removed in a future version of CMake.
3163 CMP0037
3165 Target names should not be reserved and should match a validity pat‐
3166 tern.
3167 CMake 2.8.12 and lower allowed creating targets using add_library(),
3169 add_executable() and add_custom_target() with unrestricted choice for
3170 the target name. Newer cmake features such as cmake-generator-expres‐
3171 sions(7) and some diagnostics expect target names to match a restricted
3172 pattern.
3173 Target names may contain upper and lower case letters, numbers, the un‐
3175 derscore character (_), dot(.), plus(+) and minus(-). As a special
3176 case, ALIAS and IMPORTED targets may contain two consecutive colons.
3177 Target names reserved by one or more CMake generators are not allowed.
3179 Among others these include all, clean, help, and install.
3180 Target names associated with optional features, such as test and pack‐
3182 age, may also be reserved. CMake 3.10 and below always reserve them.
3183 CMake 3.11 and above reserve them only when the corresponding feature
3184 is enabled (e.g. by including the CTest or CPack modules).
3185 The OLD behavior for this policy is to allow creating targets with re‐
3187 served names or which do not match the validity pattern. The NEW be‐
3188 havior for this policy is to report an error if an add_* command is
3189 used with an invalid target name.
3190 This policy was introduced in CMake version 3.0. CMake version 3.22.2
3192 warns when the policy is not set and uses OLD behavior. Use the
3193 cmake_policy() command to set it to OLD or NEW explicitly.
3194 NOTE:
3196 The OLD behavior of a policy is deprecated by definition and may be
3197 removed in a future version of CMake.
3198 CMP0036
3200 The build_name() command should not be called.
3201 This command was added in May 2001 to compute a name for the current
3203 operating system and compiler combination. The command has long been
3204 documented as discouraged and replaced by the CMAKE_SYSTEM and
3205 CMAKE_<LANG>_COMPILER variables.
3206 CMake >= 3.0 prefer that this command never be called. The OLD behav‐
3208 ior for this policy is to allow the command to be called. The NEW be‐
3209 havior for this policy is to issue a FATAL_ERROR when the command is
3210 called.
3211 This policy was introduced in CMake version 3.0. CMake version 3.22.2
3213 warns when the policy is not set and uses OLD behavior. Use the
3214 cmake_policy() command to set it to OLD or NEW explicitly.
3215 NOTE:
3217 The OLD behavior of a policy is deprecated by definition and may be
3218 removed in a future version of CMake.
3219 CMP0035
3221 The variable_requires() command should not be called.
3222 This command was introduced in November 2001 to perform some condi‐
3224 tional logic. It has long been replaced by the if() command.
3225 CMake >= 3.0 prefer that this command never be called. The OLD behav‐
3227 ior for this policy is to allow the command to be called. The NEW be‐
3228 havior for this policy is to issue a FATAL_ERROR when the command is
3229 called.
3230 This policy was introduced in CMake version 3.0. CMake version 3.22.2
3232 warns when the policy is not set and uses OLD behavior. Use the
3233 cmake_policy() command to set it to OLD or NEW explicitly.
3234 NOTE:
3236 The OLD behavior of a policy is deprecated by definition and may be
3237 removed in a future version of CMake.
3238 CMP0034
3240 The utility_source() command should not be called.
3241 This command was introduced in March 2001 to help build executables
3243 used to generate other files. This approach has long been replaced by
3244 add_executable() combined with add_custom_command().
3245 CMake >= 3.0 prefer that this command never be called. The OLD behav‐
3247 ior for this policy is to allow the command to be called. The NEW be‐
3248 havior for this policy is to issue a FATAL_ERROR when the command is
3249 called.
3250 This policy was introduced in CMake version 3.0. CMake version 3.22.2
3252 warns when the policy is not set and uses OLD behavior. Use the
3253 cmake_policy() command to set it to OLD or NEW explicitly.
3254 NOTE:
3256 The OLD behavior of a policy is deprecated by definition and may be
3257 removed in a future version of CMake.
3258 CMP0033
3260 The export_library_dependencies() command should not be called.
3261 This command was added in January 2003 to export <tgt>_LIB_DEPENDS in‐
3263 ternal CMake cache entries to a file for installation with a project.
3264 This was used at the time to allow transitive link dependencies to work
3265 for applications outside of the original build tree of a project. The
3266 functionality has been superseded by the export() and install(EXPORT)
3267 commands.
3268 CMake >= 3.0 prefer that this command never be called. The OLD behav‐
3270 ior for this policy is to allow the command to be called. The NEW be‐
3271 havior for this policy is to issue a FATAL_ERROR when the command is
3272 called.
3273 This policy was introduced in CMake version 3.0. CMake version 3.22.2
3275 warns when the policy is not set and uses OLD behavior. Use the
3276 cmake_policy() command to set it to OLD or NEW explicitly.
3277 NOTE:
3279 The OLD behavior of a policy is deprecated by definition and may be
3280 removed in a future version of CMake.
3281 CMP0032
3283 The output_required_files() command should not be called.
3284 This command was added in June 2001 to expose the then-current CMake
3286 implicit dependency scanner. CMake's real implicit dependency scanner
3287 has evolved since then but is not exposed through this command. The
3288 scanning capabilities of this command are very limited and this func‐
3289 tionality is better achieved through dedicated outside tools.
3290 CMake >= 3.0 prefer that this command never be called. The OLD behav‐
3292 ior for this policy is to allow the command to be called. The NEW be‐
3293 havior for this policy is to issue a FATAL_ERROR when the command is
3294 called.
3295 This policy was introduced in CMake version 3.0. CMake version 3.22.2
3297 warns when the policy is not set and uses OLD behavior. Use the
3298 cmake_policy() command to set it to OLD or NEW explicitly.
3299 NOTE:
3301 The OLD behavior of a policy is deprecated by definition and may be
3302 removed in a future version of CMake.
3303 CMP0031
3305 The load_command() command should not be called.
3306 This command was added in August 2002 to allow projects to add arbi‐
3308 trary commands implemented in C or C++. However, it does not work when
3309 the toolchain in use does not match the ABI of the CMake process. It
3310 has been mostly superseded by the macro() and function() commands.
3311 CMake >= 3.0 prefer that this command never be called. The OLD behav‐
3313 ior for this policy is to allow the command to be called. The NEW be‐
3314 havior for this policy is to issue a FATAL_ERROR when the command is
3315 called.
3316 This policy was introduced in CMake version 3.0. CMake version 3.22.2
3318 warns when the policy is not set and uses OLD behavior. Use the
3319 cmake_policy() command to set it to OLD or NEW explicitly.
3320 NOTE:
3322 The OLD behavior of a policy is deprecated by definition and may be
3323 removed in a future version of CMake.
3324 CMP0030
3326 The use_mangled_mesa() command should not be called.
3327 This command was created in September 2001 to support VTK before modern
3329 CMake language and custom command capabilities. VTK has not used it in
3330 years.
3331 CMake >= 3.0 prefer that this command never be called. The OLD behav‐
3333 ior for this policy is to allow the command to be called. The NEW be‐
3334 havior for this policy is to issue a FATAL_ERROR when the command is
3335 called.
3336 This policy was introduced in CMake version 3.0. CMake version 3.22.2
3338 warns when the policy is not set and uses OLD behavior. Use the
3339 cmake_policy() command to set it to OLD or NEW explicitly.
3340 NOTE:
3342 The OLD behavior of a policy is deprecated by definition and may be
3343 removed in a future version of CMake.
3344 CMP0029
3346 The subdir_depends() command should not be called.
3347 The implementation of this command has been empty since December 2001
3349 but was kept in CMake for compatibility for a long time.
3350 CMake >= 3.0 prefer that this command never be called. The OLD behav‐
3352 ior for this policy is to allow the command to be called. The NEW be‐
3353 havior for this policy is to issue a FATAL_ERROR when the command is
3354 called.
3355 This policy was introduced in CMake version 3.0. CMake version 3.22.2
3357 warns when the policy is not set and uses OLD behavior. Use the
3358 cmake_policy() command to set it to OLD or NEW explicitly.
3359 NOTE:
3361 The OLD behavior of a policy is deprecated by definition and may be
3362 removed in a future version of CMake.
3363 CMP0028
3365 Double colon in target name means ALIAS or IMPORTED target.
3366 CMake 2.8.12 and lower allowed the use of targets and files with double
3368 colons in target_link_libraries(), with some buildsystem generators.
3369 The use of double-colons is a common pattern used to namespace IMPORTED
3371 targets and ALIAS targets. When computing the link dependencies of a
3372 target, the name of each dependency could either be a target, or a file
3373 on disk. Previously, if a target was not found with a matching name,
3374 the name was considered to refer to a file on disk. This can lead to
3375 confusing error messages if there is a typo in what should be a target
3376 name.
3377 The OLD behavior for this policy is to search for targets, then files
3379 on disk, even if the search term contains double-colons. The NEW be‐
3380 havior for this policy is to issue a FATAL_ERROR if a link dependency
3381 contains double-colons but is not an IMPORTED target or an ALIAS tar‐
3382 get.
3383 This policy was introduced in CMake version 3.0. CMake version 3.22.2
3385 warns when the policy is not set and uses OLD behavior. Use the
3386 cmake_policy() command to set it to OLD or NEW explicitly.
3387 NOTE:
3389 The OLD behavior of a policy is deprecated by definition and may be
3390 removed in a future version of CMake.
3391 CMP0027
3393 Conditionally linked imported targets with missing include directories.
3394 CMake 2.8.11 introduced introduced the concept of INTERFACE_INCLUDE_DI‐
3396 RECTORIES, and a check at cmake time that the entries in the INTER‐
3397 FACE_INCLUDE_DIRECTORIES of an IMPORTED target actually exist. CMake
3398 2.8.11 also introduced generator expression support in the tar‐
3399 get_link_libraries() command. However, if an imported target is linked
3400 as a result of a generator expression evaluation, the entries in the
3401 INTERFACE_INCLUDE_DIRECTORIES of that target were not checked for exis‐
3402 tence as they should be.
3403 The OLD behavior of this policy is to report a warning if an entry in
3405 the INTERFACE_INCLUDE_DIRECTORIES of a generator-expression condition‐
3406 ally linked IMPORTED target does not exist.
3407 The NEW behavior of this policy is to report an error if an entry in
3409 the INTERFACE_INCLUDE_DIRECTORIES of a generator-expression condition‐
3410 ally linked IMPORTED target does not exist.
3411 This policy was introduced in CMake version 3.0. CMake version 3.22.2
3413 warns when the policy is not set and uses OLD behavior. Use the
3414 cmake_policy() command to set it to OLD or NEW explicitly.
3415 NOTE:
3417 The OLD behavior of a policy is deprecated by definition and may be
3418 removed in a future version of CMake.
3419 CMP0026
3421 Disallow use of the LOCATION property for build targets.
3422 CMake 2.8.12 and lower allowed reading the LOCATION target property
3424 (and configuration-specific variants) to determine the eventual loca‐
3425 tion of build targets. This relies on the assumption that all neces‐
3426 sary information is available at configure-time to determine the final
3427 location and filename of the target. However, this property is not
3428 fully determined until later at generate-time. At generate time, the
3429 $<TARGET_FILE> generator expression can be used to determine the even‐
3430 tual LOCATION of a target output.
3431 Code which reads the LOCATION target property can be ported to use the
3433 $<TARGET_FILE> generator expression together with the file(GENERATE)
3434 subcommand to generate a file containing the target location.
3435 The OLD behavior for this policy is to allow reading the LOCATION prop‐
3437 erties from build-targets. The NEW behavior for this policy is to not
3438 to allow reading the LOCATION properties from build-targets.
3439 This policy was introduced in CMake version 3.0. CMake version 3.22.2
3441 warns when the policy is not set and uses OLD behavior. Use the
3442 cmake_policy() command to set it to OLD or NEW explicitly.
3443 NOTE:
3445 The OLD behavior of a policy is deprecated by definition and may be
3446 removed in a future version of CMake.
3447 CMP0025
3449 Compiler id for Apple Clang is now AppleClang.
3450 CMake 3.0 and above recognize that Apple Clang is a different compiler
3452 than upstream Clang and that they have different version numbers.
3453 CMake now prefers to present this to projects by setting the
3454 CMAKE_<LANG>_COMPILER_ID variable to AppleClang instead of Clang. How‐
3455 ever, existing projects may assume the compiler id for Apple Clang is
3456 just Clang as it was in CMake versions prior to 3.0. Therefore this
3457 policy determines for Apple Clang which compiler id to report in the
3458 CMAKE_<LANG>_COMPILER_ID variable after language <LANG> is enabled by
3459 the project() or enable_language() command. The policy must be set
3460 prior to the invocation of either command.
3461 The OLD behavior for this policy is to use compiler id Clang. The NEW
3463 behavior for this policy is to use compiler id AppleClang.
3464 This policy was introduced in CMake version 3.0. Use the cmake_pol‐
3466 icy() command to set this policy to OLD or NEW explicitly. Unlike most
3467 policies, CMake version 3.22.2 does not warn by default when this pol‐
3468 icy is not set and simply uses OLD behavior. See documentation of the
3469 CMAKE_POLICY_WARNING_CMP0025 variable to control the warning.
3470 NOTE:
3472 The OLD behavior of a policy is deprecated by definition and may be
3473 removed in a future version of CMake.
3474 CMP0024
3476 Disallow include export result.
3477 CMake 2.8.12 and lower allowed use of the include() command with the
3479 result of the export() command. This relies on the assumption that the
3480 export() command has an immediate effect at configure-time during a
3481 cmake run. Certain properties of targets are not fully determined un‐
3482 til later at generate-time, such as the link language and complete list
3483 of link libraries. Future refactoring will change the effect of the
3484 export() command to be executed at generate-time. Use ALIAS targets
3485 instead in cases where the goal is to refer to targets by another name.
3486 The OLD behavior for this policy is to allow including the result of an
3488 export() command. The NEW behavior for this policy is not to allow in‐
3489 cluding the result of an export() command.
3490 This policy was introduced in CMake version 3.0. CMake version 3.22.2
3492 warns when the policy is not set and uses OLD behavior. Use the
3493 cmake_policy() command to set it to OLD or NEW explicitly.
3494 NOTE:
3496 The OLD behavior of a policy is deprecated by definition and may be
3497 removed in a future version of CMake.
3498
3500 CMP0023
3501 Plain and keyword target_link_libraries() signatures cannot be mixed.
3502 CMake 2.8.12 introduced the target_link_libraries() signature using the
3504 PUBLIC, PRIVATE, and INTERFACE keywords to generalize the LINK_PUBLIC
3505 and LINK_PRIVATE keywords introduced in CMake 2.8.7. Use of signatures
3506 with any of these keywords sets the link interface of a target explic‐
3507 itly, even if empty. This produces confusing behavior when used in
3508 combination with the historical behavior of the plain target_link_li‐
3509 braries() signature. For example, consider the code:
3510 target_link_libraries(mylib A)
3512 target_link_libraries(mylib PRIVATE B)
3513 After the first line the link interface has not been set explicitly so
3515 CMake would use the link implementation, A, as the link interface.
3516 However, the second line sets the link interface to empty. In order to
3517 avoid this subtle behavior CMake now prefers to disallow mixing the
3518 plain and keyword signatures of target_link_libraries() for a single
3519 target.
3520 The OLD behavior for this policy is to allow keyword and plain tar‐
3522 get_link_libraries() signatures to be mixed. The NEW behavior for this
3523 policy is to not to allow mixing of the keyword and plain signatures.
3524 This policy was introduced in CMake version 2.8.12. CMake version
3526 3.22.2 warns when the policy is not set and uses OLD behavior. Use the
3527 cmake_policy() command to set it to OLD or NEW explicitly.
3528 NOTE:
3530 The OLD behavior of a policy is deprecated by definition and may be
3531 removed in a future version of CMake.
3532 CMP0022
3534 INTERFACE_LINK_LIBRARIES defines the link interface.
3535 CMake 2.8.11 constructed the 'link interface' of a target from proper‐
3537 ties matching (IMPORTED_)?LINK_INTERFACE_LIBRARIES(_<CONFIG>)?. The
3538 modern way to specify config-sensitive content is to use generator ex‐
3539 pressions and the IMPORTED_ prefix makes uniform processing of the link
3540 interface with generator expressions impossible. The INTER‐
3541 FACE_LINK_LIBRARIES target property was introduced as a replacement in
3542 CMake 2.8.12. This new property is named consistently with the INTER‐
3543 FACE_COMPILE_DEFINITIONS, INTERFACE_INCLUDE_DIRECTORIES and INTER‐
3544 FACE_COMPILE_OPTIONS properties. For in-build targets, CMake will use
3545 the INTERFACE_LINK_LIBRARIES property as the source of the link inter‐
3546 face only if policy CMP0022 is NEW. When exporting a target which has
3547 this policy set to NEW, only the INTERFACE_LINK_LIBRARIES property will
3548 be processed and generated for the IMPORTED target by default. A new
3549 option to the install(EXPORT) and export commands allows export of the
3550 old-style properties for compatibility with downstream users of CMake
3551 versions older than 2.8.12. The target_link_libraries() command will
3552 no longer populate the properties matching LINK_INTERFACE_LI‐
3553 BRARIES(_<CONFIG>)? if this policy is NEW.
3554 Warning-free future-compatible code which works with CMake 2.8.7 on‐
3556 wards can be written by using the LINK_PRIVATE and LINK_PUBLIC keywords
3557 of target_link_libraries().
3558 The OLD behavior for this policy is to ignore the INTERFACE_LINK_LI‐
3560 BRARIES property for in-build targets. The NEW behavior for this pol‐
3561 icy is to use the INTERFACE_LINK_LIBRARIES property for in-build tar‐
3562 gets, and ignore the old properties matching (IMPORTED_)?LINK_INTER‐
3563 FACE_LIBRARIES(_<CONFIG>)?.
3564 This policy was introduced in CMake version 2.8.12. CMake version
3566 3.22.2 warns when the policy is not set and uses OLD behavior. Use the
3567 cmake_policy() command to set it to OLD or NEW explicitly.
3568 NOTE:
3570 The OLD behavior of a policy is deprecated by definition and may be
3571 removed in a future version of CMake.
3572 CMP0021
3574 Fatal error on relative paths in INCLUDE_DIRECTORIES target property.
3575 CMake 2.8.10.2 and lower allowed the INCLUDE_DIRECTORIES target prop‐
3577 erty to contain relative paths. The base path for such relative en‐
3578 tries is not well defined. CMake 2.8.12 issues a FATAL_ERROR if the
3579 INCLUDE_DIRECTORIES property contains a relative path.
3580 The OLD behavior for this policy is not to warn about relative paths in
3582 the INCLUDE_DIRECTORIES target property. The NEW behavior for this
3583 policy is to issue a FATAL_ERROR if INCLUDE_DIRECTORIES contains a rel‐
3584 ative path.
3585 This policy was introduced in CMake version 2.8.12. CMake version
3587 3.22.2 warns when the policy is not set and uses OLD behavior. Use the
3588 cmake_policy() command to set it to OLD or NEW explicitly.
3589 NOTE:
3591 The OLD behavior of a policy is deprecated by definition and may be
3592 removed in a future version of CMake.
3593 CMP0020
3595 Automatically link Qt executables to qtmain target on Windows.
3596 CMake 2.8.10 and lower required users of Qt to always specify a link
3598 dependency to the qtmain.lib static library manually on Windows. CMake
3599 2.8.11 gained the ability to evaluate generator expressions while de‐
3600 termining the link dependencies from IMPORTED targets. This allows
3601 CMake itself to automatically link executables which link to Qt to the
3602 qtmain.lib library when using IMPORTED Qt targets. For applications
3603 already linking to qtmain.lib, this should have little impact. For ap‐
3604 plications which supply their own alternative WinMain implementation
3605 and for applications which use the QAxServer library, this automatic
3606 linking will need to be disabled as per the documentation.
3607 The OLD behavior for this policy is not to link executables to qt‐
3609 main.lib automatically when they link to the QtCore IMPORTED target.
3610 The NEW behavior for this policy is to link executables to qtmain.lib
3611 automatically when they link to QtCore IMPORTED target.
3612 This policy was introduced in CMake version 2.8.11. CMake version
3614 3.22.2 warns when the policy is not set and uses OLD behavior. Use the
3615 cmake_policy() command to set it to OLD or NEW explicitly.
3616 NOTE:
3618 The OLD behavior of a policy is deprecated by definition and may be
3619 removed in a future version of CMake.
3620 CMP0019
3622 Do not re-expand variables in include and link information.
3623 CMake 2.8.10 and lower re-evaluated values given to the include_direc‐
3625 tories, link_directories, and link_libraries commands to expand any
3626 leftover variable references at the end of the configuration step.
3627 This was for strict compatibility with VERY early CMake versions be‐
3628 cause all variable references are now normally evaluated during CMake
3629 language processing. CMake 2.8.11 and higher prefer to skip the extra
3630 evaluation.
3631 The OLD behavior for this policy is to re-evaluate the values for
3633 strict compatibility. The NEW behavior for this policy is to leave the
3634 values untouched.
3635 This policy was introduced in CMake version 2.8.11. CMake version
3637 3.22.2 warns when the policy is not set and uses OLD behavior. Use the
3638 cmake_policy() command to set it to OLD or NEW explicitly.
3639 NOTE:
3641 The OLD behavior of a policy is deprecated by definition and may be
3642 removed in a future version of CMake.
3643 CMP0018
3645 Ignore CMAKE_SHARED_LIBRARY_<Lang>_FLAGS variable.
3646 CMake 2.8.8 and lower compiled sources in SHARED and MODULE libraries
3648 using the value of the undocumented CMAKE_SHARED_LIBRARY_<Lang>_FLAGS
3649 platform variable. The variable contained platform-specific flags
3650 needed to compile objects for shared libraries. Typically it included
3651 a flag such as -fPIC for position independent code but also included
3652 other flags needed on certain platforms. CMake 2.8.9 and higher prefer
3653 instead to use the POSITION_INDEPENDENT_CODE target property to deter‐
3654 mine what targets should be position independent, and new undocumented
3655 platform variables to select flags while ignoring CMAKE_SHARED_LI‐
3656 BRARY_<Lang>_FLAGS completely.
3657 The default for either approach produces identical compilation flags,
3659 but if a project modifies CMAKE_SHARED_LIBRARY_<Lang>_FLAGS from its
3660 original value this policy determines which approach to use.
3661 The OLD behavior for this policy is to ignore the POSITION_INDEPEN‐
3663 DENT_CODE property for all targets and use the modified value of
3664 CMAKE_SHARED_LIBRARY_<Lang>_FLAGS for SHARED and MODULE libraries.
3665 The NEW behavior for this policy is to ignore CMAKE_SHARED_LI‐
3667 BRARY_<Lang>_FLAGS whether it is modified or not and honor the POSI‐
3668 TION_INDEPENDENT_CODE target property.
3669 This policy was introduced in CMake version 2.8.9. CMake version
3671 3.22.2 warns when the policy is not set and uses OLD behavior. Use the
3672 cmake_policy() command to set it to OLD or NEW explicitly.
3673 NOTE:
3675 The OLD behavior of a policy is deprecated by definition and may be
3676 removed in a future version of CMake.
3677 CMP0017
3679 Prefer files from the CMake module directory when including from there.
3680 Starting with CMake 2.8.4, if a cmake-module shipped with CMake (i.e.
3682 located in the CMake module directory) calls include() or find_pack‐
3683 age(), the files located in the CMake module directory are preferred
3684 over the files in CMAKE_MODULE_PATH. This makes sure that the modules
3685 belonging to CMake always get those files included which they expect,
3686 and against which they were developed and tested. In all other cases,
3687 the files found in CMAKE_MODULE_PATH still take precedence over the
3688 ones in the CMake module directory. The OLD behavior is to always pre‐
3689 fer files from CMAKE_MODULE_PATH over files from the CMake modules di‐
3690 rectory.
3691 This policy was introduced in CMake version 2.8.4. CMake version
3693 3.22.2 warns when the policy is not set and uses OLD behavior. Use the
3694 cmake_policy() command to set it to OLD or NEW explicitly.
3695 NOTE:
3697 The OLD behavior of a policy is deprecated by definition and may be
3698 removed in a future version of CMake.
3699 CMP0016
3701 target_link_libraries() reports error if its only argument is not a
3702 target.
3703 In CMake 2.8.2 and lower the target_link_libraries() command silently
3705 ignored if it was called with only one argument, and this argument
3706 wasn't a valid target. In CMake 2.8.3 and above it reports an error in
3707 this case.
3708 This policy was introduced in CMake version 2.8.3. CMake version
3710 3.22.2 warns when the policy is not set and uses OLD behavior. Use the
3711 cmake_policy() command to set it to OLD or NEW explicitly.
3712 NOTE:
3714 The OLD behavior of a policy is deprecated by definition and may be
3715 removed in a future version of CMake.
3716 CMP0015
3718 link_directories() treats paths relative to the source dir.
3719 In CMake 2.8.0 and lower the link_directories() command passed relative
3721 paths unchanged to the linker. In CMake 2.8.1 and above the link_di‐
3722 rectories() command prefers to interpret relative paths with respect to
3723 CMAKE_CURRENT_SOURCE_DIR, which is consistent with include_directo‐
3724 ries() and other commands. The OLD behavior for this policy is to use
3725 relative paths verbatim in the linker command. The NEW behavior for
3726 this policy is to convert relative paths to absolute paths by appending
3727 the relative path to CMAKE_CURRENT_SOURCE_DIR.
3728 This policy was introduced in CMake version 2.8.1. CMake version
3730 3.22.2 warns when the policy is not set and uses OLD behavior. Use the
3731 cmake_policy() command to set it to OLD or NEW explicitly.
3732 NOTE:
3734 The OLD behavior of a policy is deprecated by definition and may be
3735 removed in a future version of CMake.
3736 CMP0014
3738 Input directories must have CMakeLists.txt.
3739 CMake versions before 2.8 silently ignored missing CMakeLists.txt files
3741 in directories referenced by add_subdirectory() or subdirs(), treating
3742 them as if present but empty. In CMake 2.8.0 and above this cmake_pol‐
3743 icy() determines whether or not the case is an error. The OLD behavior
3744 for this policy is to silently ignore the problem. The NEW behavior
3745 for this policy is to report an error.
3746 This policy was introduced in CMake version 2.8.0. CMake version
3748 3.22.2 warns when the policy is not set and uses OLD behavior. Use the
3749 cmake_policy() command to set it to OLD or NEW explicitly.
3750 NOTE:
3752 The OLD behavior of a policy is deprecated by definition and may be
3753 removed in a future version of CMake.
3754 CMP0013
3756 Duplicate binary directories are not allowed.
3757 CMake 2.6.3 and below silently permitted add_subdirectory() calls to
3759 create the same binary directory multiple times. During build system
3760 generation files would be written and then overwritten in the build
3761 tree and could lead to strange behavior. CMake 2.6.4 and above explic‐
3762 itly detect duplicate binary directories. CMake 2.6.4 always considers
3763 this case an error. In CMake 2.8.0 and above this policy determines
3764 whether or not the case is an error. The OLD behavior for this policy
3765 is to allow duplicate binary directories. The NEW behavior for this
3766 policy is to disallow duplicate binary directories with an error.
3767 This policy was introduced in CMake version 2.8.0. CMake version
3769 3.22.2 warns when the policy is not set and uses OLD behavior. Use the
3770 cmake_policy() command to set it to OLD or NEW explicitly.
3771 NOTE:
3773 The OLD behavior of a policy is deprecated by definition and may be
3774 removed in a future version of CMake.
3775 CMP0012
3777 if() recognizes numbers and boolean constants.
3778 In CMake versions 2.6.4 and lower the if() command implicitly derefer‐
3780 enced arguments corresponding to variables, even those named like num‐
3781 bers or boolean constants, except for 0 and 1. Numbers and boolean
3782 constants such as true, false, yes, no, on, off, y, n, notfound, ignore
3783 (all case insensitive) were recognized in some cases but not all. For
3784 example, the code if(TRUE) might have evaluated as false. Numbers such
3785 as 2 were recognized only in boolean expressions like if(NOT 2) (lead‐
3786 ing to false) but not as a single-argument like if(2) (also leading to
3787 false). Later versions of CMake prefer to treat numbers and boolean
3788 constants literally, so they should not be used as variable names.
3789 The OLD behavior for this policy is to implicitly dereference variables
3791 named like numbers and boolean constants. The NEW behavior for this
3792 policy is to recognize numbers and boolean constants without derefer‐
3793 encing variables with such names.
3794 This policy was introduced in CMake version 2.8.0. CMake version
3796 3.22.2 warns when the policy is not set and uses OLD behavior. Use the
3797 cmake_policy() command to set it to OLD or NEW explicitly.
3798 NOTE:
3800 The OLD behavior of a policy is deprecated by definition and may be
3801 removed in a future version of CMake.
3802
3804 CMP0011
3805 Included scripts do automatic cmake_policy() PUSH and POP.
3806 In CMake 2.6.2 and below, CMake Policy settings in scripts loaded by
3808 the include() and find_package() commands would affect the includer.
3809 Explicit invocations of cmake_policy(PUSH) and cmake_policy(POP) were
3810 required to isolate policy changes and protect the includer. While
3811 some scripts intend to affect the policies of their includer, most do
3812 not. In CMake 2.6.3 and above, include() and find_package() by default
3813 PUSH and POP an entry on the policy stack around an included script,
3814 but provide a NO_POLICY_SCOPE option to disable it. This policy deter‐
3815 mines whether or not to imply NO_POLICY_SCOPE for compatibility. The
3816 OLD behavior for this policy is to imply NO_POLICY_SCOPE for include()
3817 and find_package() commands. The NEW behavior for this policy is to
3818 allow the commands to do their default cmake_policy PUSH and POP.
3819 This policy was introduced in CMake version 2.6.3. CMake version
3821 3.22.2 warns when the policy is not set and uses OLD behavior. Use the
3822 cmake_policy() command to set it to OLD or NEW explicitly.
3823 NOTE:
3825 The OLD behavior of a policy is deprecated by definition and may be
3826 removed in a future version of CMake.
3827 CMP0010
3829 Bad variable reference syntax is an error.
3830 In CMake 2.6.2 and below, incorrect variable reference syntax such as a
3832 missing close-brace (${FOO) was reported but did not stop processing of
3833 CMake code. This policy determines whether a bad variable reference is
3834 an error. The OLD behavior for this policy is to warn about the error,
3835 leave the string untouched, and continue. The NEW behavior for this
3836 policy is to report an error.
3837 If CMP0053 is set to NEW, this policy has no effect and is treated as
3839 always being NEW.
3840 This policy was introduced in CMake version 2.6.3. CMake version
3842 3.22.2 warns when the policy is not set and uses OLD behavior. Use the
3843 cmake_policy() command to set it to OLD or NEW explicitly.
3844 NOTE:
3846 The OLD behavior of a policy is deprecated by definition and may be
3847 removed in a future version of CMake.
3848 CMP0009
3850 FILE GLOB_RECURSE calls should not follow symlinks by default.
3851 In CMake 2.6.1 and below, file(GLOB_RECURSE) calls would follow through
3853 symlinks, sometimes coming up with unexpectedly large result sets be‐
3854 cause of symlinks to top level directories that contain hundreds of
3855 thousands of files.
3856 This policy determines whether or not to follow symlinks encountered
3858 during a file(GLOB_RECURSE) call. The OLD behavior for this policy is
3859 to follow the symlinks. The NEW behavior for this policy is not to
3860 follow the symlinks by default, but only if FOLLOW_SYMLINKS is given as
3861 an additional argument to the FILE command.
3862 This policy was introduced in CMake version 2.6.2. CMake version
3864 3.22.2 warns when the policy is not set and uses OLD behavior. Use the
3865 cmake_policy() command to set it to OLD or NEW explicitly.
3866 NOTE:
3868 The OLD behavior of a policy is deprecated by definition and may be
3869 removed in a future version of CMake.
3870 CMP0008
3872 Libraries linked by full-path must have a valid library file name.
3873 In CMake 2.4 and below it is possible to write code like
3875 target_link_libraries(myexe /full/path/to/somelib)
3877 where somelib is supposed to be a valid library file name such as lib‐
3879 somelib.a or somelib.lib. For Makefile generators this produces an er‐
3880 ror at build time because the dependency on the full path cannot be
3881 found. For Visual Studio Generators IDE and Xcode generators this used
3882 to work by accident because CMake would always split off the library
3883 directory and ask the linker to search for the library by name
3884 (-lsomelib or somelib.lib). Despite the failure with Makefiles, some
3885 projects have code like this and build only with Visual Studio and/or
3886 Xcode. This version of CMake prefers to pass the full path directly to
3887 the native build tool, which will fail in this case because it does not
3888 name a valid library file.
3889 This policy determines what to do with full paths that do not appear to
3891 name a valid library file. The OLD behavior for this policy is to
3892 split the library name from the path and ask the linker to search for
3893 it. The NEW behavior for this policy is to trust the given path and
3894 pass it directly to the native build tool unchanged.
3895 This policy was introduced in CMake version 2.6.1. CMake version
3897 3.22.2 warns when the policy is not set and uses OLD behavior. Use the
3898 cmake_policy() command to set it to OLD or NEW explicitly.
3899 NOTE:
3901 The OLD behavior of a policy is deprecated by definition and may be
3902 removed in a future version of CMake.
3903 CMP0007
3905 list command no longer ignores empty elements.
3906 This policy determines whether the list command will ignore empty ele‐
3908 ments in the list. CMake 2.4 and below list commands ignored all empty
3909 elements in the list. For example, a;b;;c would have length 3 and not
3910 4. The OLD behavior for this policy is to ignore empty list elements.
3911 The NEW behavior for this policy is to correctly count empty elements
3912 in a list.
3913 This policy was introduced in CMake version 2.6.0. CMake version
3915 3.22.2 warns when the policy is not set and uses OLD behavior. Use the
3916 cmake_policy() command to set it to OLD or NEW explicitly.
3917 NOTE:
3919 The OLD behavior of a policy is deprecated by definition and may be
3920 removed in a future version of CMake.
3921 CMP0006
3923 Installing MACOSX_BUNDLE targets requires a BUNDLE DESTINATION.
3924 This policy determines whether the install(TARGETS) command must be
3926 given a BUNDLE DESTINATION when asked to install a target with the MA‐
3927 COSX_BUNDLE property set. CMake 2.4 and below did not distinguish ap‐
3928 plication bundles from normal executables when installing targets.
3929 CMake 2.6 provides a BUNDLE option to the install(TARGETS) command that
3930 specifies rules specific to application bundles on the Mac. Projects
3931 should use this option when installing a target with the MACOSX_BUNDLE
3932 property set.
3933 The OLD behavior for this policy is to fall back to the RUNTIME DESTI‐
3935 NATION if a BUNDLE DESTINATION is not given. The NEW behavior for this
3936 policy is to produce an error if a bundle target is installed without a
3937 BUNDLE DESTINATION.
3938 This policy was introduced in CMake version 2.6.0. CMake version
3940 3.22.2 warns when the policy is not set and uses OLD behavior. Use the
3941 cmake_policy() command to set it to OLD or NEW explicitly.
3942 NOTE:
3944 The OLD behavior of a policy is deprecated by definition and may be
3945 removed in a future version of CMake.
3946 CMP0005
3948 Preprocessor definition values are now escaped automatically.
3949 This policy determines whether or not CMake should generate escaped
3951 preprocessor definition values added via add_definitions. CMake ver‐
3952 sions 2.4 and below assumed that only trivial values would be given for
3953 macros in add_definitions calls. It did not attempt to escape
3954 non-trivial values such as string literals in generated build rules.
3955 CMake versions 2.6 and above support escaping of most values, but can‐
3956 not assume the user has not added escapes already in an attempt to work
3957 around limitations in earlier versions.
3958 The OLD behavior for this policy is to place definition values given to
3960 add_definitions directly in the generated build rules without attempt‐
3961 ing to escape anything. The NEW behavior for this policy is to gener‐
3962 ate correct escapes for all native build tools automatically. See doc‐
3963 umentation of the COMPILE_DEFINITIONS target property for limitations
3964 of the escaping implementation.
3965 This policy was introduced in CMake version 2.6.0. CMake version
3967 3.22.2 warns when the policy is not set and uses OLD behavior. Use the
3968 cmake_policy() command to set it to OLD or NEW explicitly.
3969 NOTE:
3971 The OLD behavior of a policy is deprecated by definition and may be
3972 removed in a future version of CMake.
3973 CMP0004
3975 Libraries linked may not have leading or trailing whitespace.
3976 CMake versions 2.4 and below silently removed leading and trailing
3978 whitespace from libraries linked with code like
3979 target_link_libraries(myexe " A ")
3981 This could lead to subtle errors in user projects.
3983 The OLD behavior for this policy is to silently remove leading and
3985 trailing whitespace. The NEW behavior for this policy is to diagnose
3986 the existence of such whitespace as an error. The setting for this
3987 policy used when checking the library names is that in effect when the
3988 target is created by an add_executable() or add_library() command.
3989 This policy was introduced in CMake version 2.6.0. CMake version
3991 3.22.2 warns when the policy is not set and uses OLD behavior. Use the
3992 cmake_policy() command to set it to OLD or NEW explicitly.
3993 NOTE:
3995 The OLD behavior of a policy is deprecated by definition and may be
3996 removed in a future version of CMake.
3997 CMP0003
3999 Libraries linked via full path no longer produce linker search paths.
4000 This policy affects how libraries whose full paths are NOT known are
4002 found at link time, but was created due to a change in how CMake deals
4003 with libraries whose full paths are known. Consider the code
4004 target_link_libraries(myexe /path/to/libA.so)
4006 CMake 2.4 and below implemented linking to libraries whose full paths
4008 are known by splitting them on the link line into separate components
4009 consisting of the linker search path and the library name. The example
4010 code might have produced something like
4011 ... -L/path/to -lA ...
4013 in order to link to library A. An analysis was performed to order mul‐
4015 tiple link directories such that the linker would find library A in the
4016 desired location, but there are cases in which this does not work.
4017 CMake versions 2.6 and above use the more reliable approach of passing
4018 the full path to libraries directly to the linker in most cases. The
4019 example code now produces something like
4020 ... /path/to/libA.so ....
4022 Unfortunately this change can break code like
4024 target_link_libraries(myexe /path/to/libA.so B)
4026 where B is meant to find /path/to/libB.so. This code is wrong because
4028 the user is asking the linker to find library B but has not provided a
4029 linker search path (which may be added with the link_directories com‐
4030 mand). However, with the old linking implementation the code would
4031 work accidentally because the linker search path added for library A
4032 allowed library B to be found.
4033 In order to support projects depending on linker search paths added by
4035 linking to libraries with known full paths, the OLD behavior for this
4036 policy will add the linker search paths even though they are not needed
4037 for their own libraries. When this policy is set to OLD, CMake will
4038 produce a link line such as
4039 ... -L/path/to /path/to/libA.so -lB ...
4041 which will allow library B to be found as it was previously. When this
4043 policy is set to NEW, CMake will produce a link line such as
4044 ... /path/to/libA.so -lB ...
4046 which more accurately matches what the project specified.
4048 The setting for this policy used when generating the link line is that
4050 in effect when the target is created by an add_executable or add_li‐
4051 brary command. For the example described above, the code
4052 cmake_policy(SET CMP0003 OLD) # or cmake_policy(VERSION 2.4)
4054 add_executable(myexe myexe.c)
4055 target_link_libraries(myexe /path/to/libA.so B)
4056 will work and suppress the warning for this policy. It may also be up‐
4058 dated to work with the corrected linking approach:
4059 cmake_policy(SET CMP0003 NEW) # or cmake_policy(VERSION 2.6)
4061 link_directories(/path/to) # needed to find library B
4062 add_executable(myexe myexe.c)
4063 target_link_libraries(myexe /path/to/libA.so B)
4064 Even better, library B may be specified with a full path:
4066 add_executable(myexe myexe.c)
4068 target_link_libraries(myexe /path/to/libA.so /path/to/libB.so)
4069 When all items on the link line have known paths CMake does not check
4071 this policy so it has no effect.
4072 Note that the warning for this policy will be issued for at most one
4074 target. This avoids flooding users with messages for every target when
4075 setting the policy once will probably fix all targets.
4076 This policy was introduced in CMake version 2.6.0. CMake version
4078 3.22.2 warns when the policy is not set and uses OLD behavior. Use the
4079 cmake_policy() command to set it to OLD or NEW explicitly.
4080 NOTE:
4082 The OLD behavior of a policy is deprecated by definition and may be
4083 removed in a future version of CMake.
4084 CMP0002
4086 Logical target names must be globally unique.
4087 Targets names created with add_executable(), add_library(), or add_cus‐
4089 tom_target() are logical build target names. Logical target names must
4090 be globally unique because:
4091 - Unique names may be referenced unambiguously both in CMake
4093 code and on make tool command lines.
4094 - Logical names are used by Xcode and VS IDE generators
4095 to produce meaningful project names for the targets.
4096 The logical name of executable and library targets does not have to
4098 correspond to the physical file names built. Consider using the OUT‐
4099 PUT_NAME target property to create two targets with the same physical
4100 name while keeping logical names distinct. Custom targets must simply
4101 have globally unique names (unless one uses the global property AL‐
4102 LOW_DUPLICATE_CUSTOM_TARGETS with a Makefiles generator).
4103 This policy was introduced in CMake version 2.6.0. CMake version
4105 3.22.2 warns when the policy is not set and uses OLD behavior. Use the
4106 cmake_policy() command to set it to OLD or NEW explicitly.
4107 NOTE:
4109 The OLD behavior of a policy is deprecated by definition and may be
4110 removed in a future version of CMake.
4111 CMP0001
4113 CMAKE_BACKWARDS_COMPATIBILITY should no longer be used.
4114 The behavior is to check CMAKE_BACKWARDS_COMPATIBILITY and present it
4116 to the user. The NEW behavior is to ignore CMAKE_BACKWARDS_COMPATIBIL‐
4117 ITY completely.
4118 In CMake 2.4 and below the variable CMAKE_BACKWARDS_COMPATIBILITY was
4120 used to request compatibility with earlier versions of CMake. In CMake
4121 2.6 and above all compatibility issues are handled by policies and the
4122 cmake_policy() command. However, CMake must still check CMAKE_BACK‐
4123 WARDS_COMPATIBILITY for projects written for CMake 2.4 and below.
4124 This policy was introduced in CMake version 2.6.0. CMake version
4126 3.22.2 warns when the policy is not set and uses OLD behavior. Use the
4127 cmake_policy() command to set it to OLD or NEW explicitly.
4128 NOTE:
4130 The OLD behavior of a policy is deprecated by definition and may be
4131 removed in a future version of CMake.
4132 CMP0000
4134 A minimum required CMake version must be specified.
4135 CMake requires that projects specify the version of CMake to which they
4137 have been written. This policy has been put in place so users trying
4138 to build the project may be told when they need to update their CMake.
4139 Specifying a version also helps the project build with CMake versions
4140 newer than that specified. Use the cmake_minimum_required() command at
4141 the top of your main CMakeLists.txt file:
4142 cmake_minimum_required(VERSION <major>.<minor>)
4144 where <major>.<minor> is the version of CMake you want to support (such
4146 as 3.14). The command will ensure that at least the given version of
4147 CMake is running and help newer versions be compatible with the
4148 project. See documentation of cmake_minimum_required() for details.
4149 Note that the command invocation must appear in the CMakeLists.txt file
4151 itself; a call in an included file is not sufficient. However, the
4152 cmake_policy() command may be called to set policy CMP0000 to OLD or
4153 NEW behavior explicitly. The OLD behavior is to silently ignore the
4154 missing invocation. The NEW behavior is to issue an error instead of a
4155 warning. An included file may set CMP0000 explicitly to affect how
4156 this policy is enforced for the main CMakeLists.txt file.
4157 This policy was introduced in CMake version 2.6.0.
4159 NOTE:
4161 The OLD behavior of a policy is deprecated by definition and may be
4162 removed in a future version of CMake.
4163
4165 2000-2022 Kitware, Inc. and Contributors
41663.22.2 Jan 25, 2022 CMAKE-POLICIES(7)