1cmakepolicies(1) General Commands Manual cmakepolicies(1)
2
6 cmakepolicies - Reference of CMake policies.
7
10 The "cmake" executable is the CMake command-line interface. It may be
11 used to configure projects in scripts. Project configuration settings
12 may be specified on the command line with the -D option. The -i option
13 will cause cmake to interactively prompt for such settings.
14 CMake is a cross-platform build system generator. Projects specify
17 their build process with platform-independent CMake listfiles included
18 in each directory of a source tree with the name CMakeLists.txt. Users
19 build a project by using CMake to generate a build system for a native
20 tool on their platform.
21
24 CMP0000
25 A minimum required CMake version must be specified.
26 CMake requires that projects specify the version of CMake to
28 which they have been written. This policy has been put in place
29 so users trying to build the project may be told when they need
30 to update their CMake. Specifying a version also helps the
31 project build with CMake versions newer than that specified.
32 Use the cmake_minimum_required command at the top of your main
33 CMakeLists.txt file:
34 cmake_minimum_required(VERSION <major>.<minor>)
37 where "<major>.<minor>" is the version of CMake you want to sup‐
39 port (such as "2.6"). The command will ensure that at least the
40 given version of CMake is running and help newer versions be
41 compatible with the project. See documentation of cmake_mini‐
42 mum_required for details.
43 Note that the command invocation must appear in the CMake‐
46 Lists.txt file itself; a call in an included file is not suffi‐
47 cient. However, the cmake_policy command may be called to set
48 policy CMP0000 to OLD or NEW behavior explicitly. The OLD
49 behavior is to silently ignore the missing invocation. The NEW
50 behavior is to issue an error instead of a warning. An included
51 file may set CMP0000 explicitly to affect how this policy is
52 enforced for the main CMakeLists.txt file.
53 This policy was introduced in CMake version 2.6.0.
56 CMP0001
59 CMAKE_BACKWARDS_COMPATIBILITY should no longer be used.
60 The OLD behavior is to check CMAKE_BACKWARDS_COMPATIBILITY and
62 present it to the user. The NEW behavior is to ignore
63 CMAKE_BACKWARDS_COMPATIBILITY completely.
64 In CMake 2.4 and below the variable CMAKE_BACKWARDS_COMPATIBIL‐
67 ITY was used to request compatibility with earlier versions of
68 CMake. In CMake 2.6 and above all compatibility issues are han‐
69 dled by policies and the cmake_policy command. However, CMake
70 must still check CMAKE_BACKWARDS_COMPATIBILITY for projects
71 written for CMake 2.4 and below.
72 This policy was introduced in CMake version 2.6.0. CMake ver‐
75 sion 2.8.4 warns when the policy is not set and uses OLD behav‐
76 ior. Use the cmake_policy command to set it to OLD or NEW
77 explicitly.
78 CMP0002
81 Logical target names must be globally unique.
82 Targets names created with add_executable, add_library, or
84 add_custom_target are logical build target names. Logical tar‐
85 get names must be globally unique because:
86 - Unique names may be referenced unambiguously both in CMake
89 code and on make tool command lines.
90 - Logical names are used by Xcode and VS IDE generators
91 to produce meaningful project names for the targets.
92 The logical name of executable and library targets does not have
94 to correspond to the physical file names built. Consider using
95 the OUTPUT_NAME target property to create two targets with the
96 same physical name while keeping logical names distinct. Custom
97 targets must simply have globally unique names (unless one uses
98 the global property ALLOW_DUPLICATE_CUSTOM_TARGETS with a Make‐
99 files generator).
100 This policy was introduced in CMake version 2.6.0. CMake ver‐
103 sion 2.8.4 warns when the policy is not set and uses OLD behav‐
104 ior. Use the cmake_policy command to set it to OLD or NEW
105 explicitly.
106 CMP0003
109 Libraries linked via full path no longer produce linker search
110 paths.
111 This policy affects how libraries whose full paths are NOT known
113 are found at link time, but was created due to a change in how
114 CMake deals with libraries whose full paths are known. Consider
115 the code
116 target_link_libraries(myexe /path/to/libA.so)
119 CMake 2.4 and below implemented linking to libraries whose full
121 paths are known by splitting them on the link line into separate
122 components consisting of the linker search path and the library
123 name. The example code might have produced something like
124 ... -L/path/to -lA ...
127 in order to link to library A. An analysis was performed to
129 order multiple link directories such that the linker would find
130 library A in the desired location, but there are cases in which
131 this does not work. CMake versions 2.6 and above use the more
132 reliable approach of passing the full path to libraries directly
133 to the linker in most cases. The example code now produces
134 something like
135 ... /path/to/libA.so ....
138 Unfortunately this change can break code like
140 target_link_libraries(myexe /path/to/libA.so B)
143 where "B" is meant to find "/path/to/libB.so". This code is
145 wrong because the user is asking the linker to find library B
146 but has not provided a linker search path (which may be added
147 with the link_directories command). However, with the old link‐
148 ing implementation the code would work accidentally because the
149 linker search path added for library A allowed library B to be
150 found.
151 In order to support projects depending on linker search paths
154 added by linking to libraries with known full paths, the OLD
155 behavior for this policy will add the linker search paths even
156 though they are not needed for their own libraries. When this
157 policy is set to OLD, CMake will produce a link line such as
158 ... -L/path/to /path/to/libA.so -lB ...
161 which will allow library B to be found as it was previously.
163 When this policy is set to NEW, CMake will produce a link line
164 such as
165 ... /path/to/libA.so -lB ...
168 which more accurately matches what the project specified.
170 The setting for this policy used when generating the link line
173 is that in effect when the target is created by an add_exe‐
174 cutable or add_library command. For the example described
175 above, the code
176 cmake_policy(SET CMP0003 OLD) # or cmake_policy(VERSION 2.4)
179 add_executable(myexe myexe.c)
180 target_link_libraries(myexe /path/to/libA.so B)
181 will work and suppress the warning for this policy. It may also
183 be updated to work with the corrected linking approach:
184 cmake_policy(SET CMP0003 NEW) # or cmake_policy(VERSION 2.6)
187 link_directories(/path/to) # needed to find library B
188 add_executable(myexe myexe.c)
189 target_link_libraries(myexe /path/to/libA.so B)
190 Even better, library B may be specified with a full path:
192 add_executable(myexe myexe.c)
195 target_link_libraries(myexe /path/to/libA.so /path/to/libB.so)
196 When all items on the link line have known paths CMake does not
198 check this policy so it has no effect.
199 Note that the warning for this policy will be issued for at most
202 one target. This avoids flooding users with messages for every
203 target when setting the policy once will probably fix all tar‐
204 gets.
205 This policy was introduced in CMake version 2.6.0. CMake ver‐
208 sion 2.8.4 warns when the policy is not set and uses OLD behav‐
209 ior. Use the cmake_policy command to set it to OLD or NEW
210 explicitly.
211 CMP0004
214 Libraries linked may not have leading or trailing whitespace.
215 CMake versions 2.4 and below silently removed leading and trail‐
217 ing whitespace from libraries linked with code like
218 target_link_libraries(myexe " A ")
221 This could lead to subtle errors in user projects.
223 The OLD behavior for this policy is to silently remove leading
226 and trailing whitespace. The NEW behavior for this policy is to
227 diagnose the existence of such whitespace as an error. The set‐
228 ting for this policy used when checking the library names is
229 that in effect when the target is created by an add_executable
230 or add_library command.
231 This policy was introduced in CMake version 2.6.0. CMake ver‐
234 sion 2.8.4 warns when the policy is not set and uses OLD behav‐
235 ior. Use the cmake_policy command to set it to OLD or NEW
236 explicitly.
237 CMP0005
240 Preprocessor definition values are now escaped automatically.
241 This policy determines whether or not CMake should generate
243 escaped preprocessor definition values added via add_defini‐
244 tions. CMake versions 2.4 and below assumed that only trivial
245 values would be given for macros in add_definitions calls. It
246 did not attempt to escape non-trivial values such as string lit‐
247 erals in generated build rules. CMake versions 2.6 and above
248 support escaping of most values, but cannot assume the user has
249 not added escapes already in an attempt to work around limita‐
250 tions in earlier versions.
251 The OLD behavior for this policy is to place definition values
254 given to add_definitions directly in the generated build rules
255 without attempting to escape anything. The NEW behavior for
256 this policy is to generate correct escapes for all native build
257 tools automatically. See documentation of the COMPILE_DEFINI‐
258 TIONS target property for limitations of the escaping implemen‐
259 tation.
260 This policy was introduced in CMake version 2.6.0. CMake ver‐
263 sion 2.8.4 warns when the policy is not set and uses OLD behav‐
264 ior. Use the cmake_policy command to set it to OLD or NEW
265 explicitly.
266 CMP0006
269 Installing MACOSX_BUNDLE targets requires a BUNDLE DESTINATION.
270 This policy determines whether the install(TARGETS) command must
272 be given a BUNDLE DESTINATION when asked to install a target
273 with the MACOSX_BUNDLE property set. CMake 2.4 and below did
274 not distinguish application bundles from normal executables when
275 installing targets. CMake 2.6 provides a BUNDLE option to the
276 install(TARGETS) command that specifies rules specific to appli‐
277 cation bundles on the Mac. Projects should use this option when
278 installing a target with the MACOSX_BUNDLE property set.
279 The OLD behavior for this policy is to fall back to the RUNTIME
282 DESTINATION if a BUNDLE DESTINATION is not given. The NEW
283 behavior for this policy is to produce an error if a bundle tar‐
284 get is installed without a BUNDLE DESTINATION.
285 This policy was introduced in CMake version 2.6.0. CMake ver‐
288 sion 2.8.4 warns when the policy is not set and uses OLD behav‐
289 ior. Use the cmake_policy command to set it to OLD or NEW
290 explicitly.
291 CMP0007
294 list command no longer ignores empty elements.
295 This policy determines whether the list command will ignore
297 empty elements in the list. CMake 2.4 and below list commands
298 ignored all empty elements in the list. For example, a;b;;c
299 would have length 3 and not 4. The OLD behavior for this policy
300 is to ignore empty list elements. The NEW behavior for this pol‐
301 icy is to correctly count empty elements in a list.
302 This policy was introduced in CMake version 2.6.0. CMake ver‐
305 sion 2.8.4 warns when the policy is not set and uses OLD behav‐
306 ior. Use the cmake_policy command to set it to OLD or NEW
307 explicitly.
308 CMP0008
311 Libraries linked by full-path must have a valid library file
312 name.
313 In CMake 2.4 and below it is possible to write code like
315 target_link_libraries(myexe /full/path/to/somelib)
318 where "somelib" is supposed to be a valid library file name such
320 as "libsomelib.a" or "somelib.lib". For Makefile generators
321 this produces an error at build time because the dependency on
322 the full path cannot be found. For VS IDE and Xcode generators
323 this used to work by accident because CMake would always split
324 off the library directory and ask the linker to search for the
325 library by name (-lsomelib or somelib.lib). Despite the failure
326 with Makefiles, some projects have code like this and build only
327 with VS and/or Xcode. This version of CMake prefers to pass the
328 full path directly to the native build tool, which will fail in
329 this case because it does not name a valid library file.
330 This policy determines what to do with full paths that do not
333 appear to name a valid library file. The OLD behavior for this
334 policy is to split the library name from the path and ask the
335 linker to search for it. The NEW behavior for this policy is to
336 trust the given path and pass it directly to the native build
337 tool unchanged.
338 This policy was introduced in CMake version 2.6.1. CMake ver‐
341 sion 2.8.4 warns when the policy is not set and uses OLD behav‐
342 ior. Use the cmake_policy command to set it to OLD or NEW
343 explicitly.
344 CMP0009
347 FILE GLOB_RECURSE calls should not follow symlinks by default.
348 In CMake 2.6.1 and below, FILE GLOB_RECURSE calls would follow
350 through symlinks, sometimes coming up with unexpectedly large
351 result sets because of symlinks to top level directories that
352 contain hundreds of thousands of files.
353 This policy determines whether or not to follow symlinks encoun‐
356 tered during a FILE GLOB_RECURSE call. The OLD behavior for this
357 policy is to follow the symlinks. The NEW behavior for this pol‐
358 icy is not to follow the symlinks by default, but only if FOL‐
359 LOW_SYMLINKS is given as an additional argument to the FILE com‐
360 mand.
361 This policy was introduced in CMake version 2.6.2. CMake ver‐
364 sion 2.8.4 warns when the policy is not set and uses OLD behav‐
365 ior. Use the cmake_policy command to set it to OLD or NEW
366 explicitly.
367 CMP0010
370 Bad variable reference syntax is an error.
371 In CMake 2.6.2 and below, incorrect variable reference syntax
373 such as a missing close-brace ("${FOO") was reported but did not
374 stop processing of CMake code. This policy determines whether a
375 bad variable reference is an error. The OLD behavior for this
376 policy is to warn about the error, leave the string untouched,
377 and continue. The NEW behavior for this policy is to report an
378 error.
379 This policy was introduced in CMake version 2.6.3. CMake ver‐
382 sion 2.8.4 warns when the policy is not set and uses OLD behav‐
383 ior. Use the cmake_policy command to set it to OLD or NEW
384 explicitly.
385 CMP0011
388 Included scripts do automatic cmake_policy PUSH and POP.
389 In CMake 2.6.2 and below, CMake Policy settings in scripts
391 loaded by the include() and find_package() commands would affect
392 the includer. Explicit invocations of cmake_policy(PUSH) and
393 cmake_policy(POP) were required to isolate policy changes and
394 protect the includer. While some scripts intend to affect the
395 policies of their includer, most do not. In CMake 2.6.3 and
396 above, include() and find_package() by default PUSH and POP an
397 entry on the policy stack around an included script, but provide
398 a NO_POLICY_SCOPE option to disable it. This policy determines
399 whether or not to imply NO_POLICY_SCOPE for compatibility. The
400 OLD behavior for this policy is to imply NO_POLICY_SCOPE for
401 include() and find_package() commands. The NEW behavior for
402 this policy is to allow the commands to do their default
403 cmake_policy PUSH and POP.
404 This policy was introduced in CMake version 2.6.3. CMake ver‐
407 sion 2.8.4 warns when the policy is not set and uses OLD behav‐
408 ior. Use the cmake_policy command to set it to OLD or NEW
409 explicitly.
410 CMP0012
413 if() recognizes numbers and boolean constants.
414 In CMake versions 2.6.4 and lower the if() command implicitly
416 dereferenced arguments corresponding to variables, even those
417 named like numbers or boolean constants, except for 0 and 1.
418 Numbers and boolean constants such as true, false, yes, no, on,
419 off, y, n, notfound, ignore (all case insensitive) were recog‐
420 nized in some cases but not all. For example, the code
421 "if(TRUE)" might have evaluated as false. Numbers such as 2
422 were recognized only in boolean expressions like "if(NOT 2)"
423 (leading to false) but not as a single-argument like "if(2)"
424 (also leading to false). Later versions of CMake prefer to treat
425 numbers and boolean constants literally, so they should not be
426 used as variable names.
427 The OLD behavior for this policy is to implicitly dereference
430 variables named like numbers and boolean constants. The NEW
431 behavior for this policy is to recognize numbers and boolean
432 constants without dereferencing variables with such names.
433 This policy was introduced in CMake version 2.8.0. CMake ver‐
436 sion 2.8.4 warns when the policy is not set and uses OLD behav‐
437 ior. Use the cmake_policy command to set it to OLD or NEW
438 explicitly.
439 CMP0013
442 Duplicate binary directories are not allowed.
443 CMake 2.6.3 and below silently permitted add_subdirectory()
445 calls to create the same binary directory multiple times. Dur‐
446 ing build system generation files would be written and then
447 overwritten in the build tree and could lead to strange behav‐
448 ior. CMake 2.6.4 and above explicitly detect duplicate binary
449 directories. CMake 2.6.4 always considers this case an error.
450 In CMake 2.8.0 and above this policy determines whether or not
451 the case is an error. The OLD behavior for this policy is to
452 allow duplicate binary directories. The NEW behavior for this
453 policy is to disallow duplicate binary directories with an
454 error.
455 This policy was introduced in CMake version 2.8.0. CMake ver‐
458 sion 2.8.4 warns when the policy is not set and uses OLD behav‐
459 ior. Use the cmake_policy command to set it to OLD or NEW
460 explicitly.
461 CMP0014
464 Input directories must have CMakeLists.txt.
465 CMake versions before 2.8 silently ignored missing CMake‐
467 Lists.txt files in directories referenced by add_subdirectory()
468 or subdirs(), treating them as if present but empty. In CMake
469 2.8.0 and above this policy determines whether or not the case
470 is an error. The OLD behavior for this policy is to silently
471 ignore the problem. The NEW behavior for this policy is to
472 report an error.
473 This policy was introduced in CMake version 2.8.0. CMake ver‐
476 sion 2.8.4 warns when the policy is not set and uses OLD behav‐
477 ior. Use the cmake_policy command to set it to OLD or NEW
478 explicitly.
479 CMP0015
482 link_directories() treats paths relative to the source dir.
483 In CMake 2.8.0 and lower the link_directories() command passed
485 relative paths unchanged to the linker. In CMake 2.8.1 and
486 above the link_directories() command prefers to interpret rela‐
487 tive paths with respect to CMAKE_CURRENT_SOURCE_DIR, which is
488 consistent with include_directories() and other commands. The
489 OLD behavior for this policy is to use relative paths verbatim
490 in the linker command. The NEW behavior for this policy is to
491 convert relative paths to absolute paths by appending the rela‐
492 tive path to CMAKE_CURRENT_SOURCE_DIR.
493 This policy was introduced in CMake version 2.8.1. CMake ver‐
496 sion 2.8.4 warns when the policy is not set and uses OLD behav‐
497 ior. Use the cmake_policy command to set it to OLD or NEW
498 explicitly.
499 CMP0016
502 target_link_libraries() reports error if only argument is not a
503 target.
504 In CMake 2.8.2 and lower the target_link_libraries() command
506 silently ignored if it was called with only one argument, and
507 this argument wasn't a valid target. In CMake 2.8.3 and above it
508 reports an error in this case.
509 This policy was introduced in CMake version 2.8.3. CMake ver‐
512 sion 2.8.4 warns when the policy is not set and uses OLD behav‐
513 ior. Use the cmake_policy command to set it to OLD or NEW
514 explicitly.
515 CMP0017
518 Prefer files from the CMake module directory when including from
519 there.
520 Starting with CMake 2.8.4, if a cmake-module shipped with CMake
522 (i.e. located in the CMake module directory) calls include() or
523 find_package(), the files located in the the CMake module direc‐
524 tory are prefered over the files in CMAKE_MODULE_PATH. This
525 makes sure that the modules belonging to CMake always get those
526 files included which they expect, and against which they were
527 developed and tested. In call other cases, the files found in
528 CMAKE_MODULE_PATH still take precedence over the ones in the
529 CMake module directory. The OLD behaviour is to always prefer
530 files from CMAKE_MODULE_PATH over files from the CMake modules
531 directory.
532 This policy was introduced in CMake version 2.8.4. CMake ver‐
535 sion 2.8.4 warns when the policy is not set and uses OLD behav‐
536 ior. Use the cmake_policy command to set it to OLD or NEW
537 explicitly.
538
541 Copyright 2000-2009 Kitware, Inc., Insight Software Consortium. All
542 rights reserved.
543 Redistribution and use in source and binary forms, with or without mod‐
546 ification, are permitted provided that the following conditions are
547 met:
548 Redistributions of source code must retain the above copyright notice,
551 this list of conditions and the following disclaimer.
552 Redistributions in binary form must reproduce the above copyright
555 notice, this list of conditions and the following disclaimer in the
556 documentation and/or other materials provided with the distribution.
557 Neither the names of Kitware, Inc., the Insight Software Consortium,
560 nor the names of their contributors may be used to endorse or promote
561 products derived from this software without specific prior written per‐
562 mission.
563 THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS
566 IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED
567 TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTIC‐
568 ULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR
569 CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
570 EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
571 PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
572 PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
573 LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
574 NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
575 SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
576
579 ccmake(1), cpack(1), ctest(1), cmakecommands(1), cmakecompat(1), cmake‐
580 modules(1), cmakeprops(1), cmakevars(1)
581 The following resources are available to get help using CMake:
584 Home Page
587 http://www.cmake.org
588 The primary starting point for learning about CMake.
590 Frequently Asked Questions
593 http://www.cmake.org/Wiki/CMake_FAQ
594 A Wiki is provided containing answers to frequently asked ques‐
596 tions.
597 Online Documentation
600 http://www.cmake.org/HTML/Documentation.html
601 Links to available documentation may be found on this web page.
603 Mailing List
606 http://www.cmake.org/HTML/MailingLists.html
607 For help and discussion about using cmake, a mailing list is
609 provided at cmake@cmake.org. The list is member-post-only but
610 one may sign up on the CMake web page. Please first read the
611 full documentation at http://www.cmake.org before posting ques‐
612 tions to the list.
613 Summary of helpful links:
616 Home: http://www.cmake.org
619 Docs: http://www.cmake.org/HTML/Documentation.html
620 Mail: http://www.cmake.org/HTML/MailingLists.html
621 FAQ: http://www.cmake.org/Wiki/CMake_FAQ
622cmake 2.8.4 March 31, 2011 cmakepolicies(1)