cmakepolicies
(1)
Name
cmakepolicies - Platform Makefile Generator.
Synopsis
Please see following description for synopsis
Description
User Commands cmakepolicies(1)
NAME
cmakepolicies - Reference of CMake policies.
NAME
cmake - Cross-Platform Makefile Generator.
DESCRIPTION
The "cmake" executable is the CMake command-line interface.
It may be used to configure projects in scripts. Project
configuration settings may be specified on the command line
with the -D option. The -i option will cause cmake to
interactively prompt for such settings.
CMake is a cross-platform build system generator. Projects
specify their build process with platform-independent CMake
listfiles included in each directory of a source tree with
the name CMakeLists.txt. Users build a project by using
CMake to generate a build system for a native tool on their
platform.
POLICIES
CMP0000
A minimum required CMake version must be specified.
CMake requires that projects specify the version of
CMake to which they have been written. This policy has
been put in place so users trying to build the project
may be told when they need to update their CMake.
Specifying a version also helps the project build with
CMake versions newer than that specified. Use the
cmake_minimum_required command at the top of your main
CMakeLists.txt file:
cmake_minimum_required(VERSION <major>.<minor>)
where "<major>.<minor>" is the version of CMake you
want to support (such as "2.6"). The command will
ensure that at least the given version of CMake is run-
ning and help newer versions be compatible with the
project. See documentation of cmake_minimum_required
for details.
Note that the command invocation must appear in the
CMakeLists.txt file itself; a call in an included file
is not sufficient. However, the cmake_policy command
may be called to set policy CMP0000 to OLD or NEW
cmake 2.8.6 Last change: June 17, 2014 1
User Commands cmakepolicies(1)
behavior explicitly. The OLD behavior is to silently
ignore the missing invocation. The NEW behavior is to
issue an error instead of a warning. An included file
may set CMP0000 explicitly to affect how this policy is
enforced for the main CMakeLists.txt file.
This policy was introduced in CMake version 2.6.0.
CMP0001
CMAKE_BACKWARDS_COMPATIBILITY should no longer be used.
The OLD behavior is to check CMAKE_BACKWARDS_COMPATI-
BILITY and present it to the user. The NEW behavior is
to ignore CMAKE_BACKWARDS_COMPATIBILITY completely.
In CMake 2.4 and below the variable CMAKE_BACK-
WARDS_COMPATIBILITY was used to request compatibility
with earlier versions of CMake. In CMake 2.6 and above
all compatibility issues are handled by policies and
the cmake_policy command. However, CMake must still
check CMAKE_BACKWARDS_COMPATIBILITY for projects writ-
ten for CMake 2.4 and below.
This policy was introduced in CMake version 2.6.0.
CMake version 2.8.6 warns when the policy is not set
and uses OLD behavior. Use the cmake_policy command to
set it to OLD or NEW explicitly.
CMP0002
Logical target names must be globally unique.
Targets names created with add_executable, add_library,
or add_custom_target are logical build target names.
Logical target names must be globally unique because:
- Unique names may be referenced unambiguously both in CMake
code and on make tool command lines.
- Logical names are used by Xcode and VS IDE generators
to produce meaningful project names for the targets.
The logical name of executable and library targets does
not have to correspond to the physical file names
built. Consider using the OUTPUT_NAME target property
to create two targets with the same physical name while
keeping logical names distinct. Custom targets must
simply have globally unique names (unless one uses the
cmake 2.8.6 Last change: June 17, 2014 2
User Commands cmakepolicies(1)
global property ALLOW_DUPLICATE_CUSTOM_TARGETS with a
Makefiles generator).
This policy was introduced in CMake version 2.6.0.
CMake version 2.8.6 warns when the policy is not set
and uses OLD behavior. Use the cmake_policy command to
set it to OLD or NEW explicitly.
CMP0003
Libraries linked via full path no longer produce linker
search paths.
This policy affects how libraries whose full paths are
NOT known are found at link time, but was created due
to a change in how CMake deals with libraries whose
full paths are known. Consider the code
target_link_libraries(myexe /path/to/libA.so)
CMake 2.4 and below implemented linking to libraries
whose full paths are known by splitting them on the
link line into separate components consisting of the
linker search path and the library name. The example
code might have produced something like
... -L/path/to -lA ...
in order to link to library A. An analysis was per-
formed to order multiple link directories such that the
linker would find library A in the desired location,
but there are cases in which this does not work. CMake
versions 2.6 and above use the more reliable approach
of passing the full path to libraries directly to the
linker in most cases. The example code now produces
something like
... /path/to/libA.so ....
Unfortunately this change can break code like
target_link_libraries(myexe /path/to/libA.so B)
where "B" is meant to find "/path/to/libB.so". This
code is wrong because the user is asking the linker to
find library B but has not provided a linker search
path (which may be added with the link_directories
cmake 2.8.6 Last change: June 17, 2014 3
User Commands cmakepolicies(1)
command). However, with the old linking implementation
the code would work accidentally because the linker
search path added for library A allowed library B to be
found.
In order to support projects depending on linker search
paths added by linking to libraries with known full
paths, the OLD behavior for this policy will add the
linker search paths even though they are not needed for
their own libraries. When this policy is set to OLD,
CMake will produce a link line such as
... -L/path/to /path/to/libA.so -lB ...
which will allow library B to be found as it was previ-
ously. When this policy is set to NEW, CMake will pro-
duce a link line such as
... /path/to/libA.so -lB ...
which more accurately matches what the project speci-
fied.
The setting for this policy used when generating the
link line is that in effect when the target is created
by an add_executable or add_library command. For the
example described above, the code
cmake_policy(SET CMP0003 OLD) # or cmake_policy(VERSION 2.4)
add_executable(myexe myexe.c)
target_link_libraries(myexe /path/to/libA.so B)
will work and suppress the warning for this policy. It
may also be updated to work with the corrected linking
approach:
cmake_policy(SET CMP0003 NEW) # or cmake_policy(VERSION 2.6)
link_directories(/path/to) # needed to find library B
add_executable(myexe myexe.c)
target_link_libraries(myexe /path/to/libA.so B)
Even better, library B may be specified with a full
path:
add_executable(myexe myexe.c)
cmake 2.8.6 Last change: June 17, 2014 4
User Commands cmakepolicies(1)
target_link_libraries(myexe /path/to/libA.so /path/to/libB.so)
When all items on the link line have known paths CMake
does not check this policy so it has no effect.
Note that the warning for this policy will be issued
for at most one target. This avoids flooding users
with messages for every target when setting the policy
once will probably fix all targets.
This policy was introduced in CMake version 2.6.0.
CMake version 2.8.6 warns when the policy is not set
and uses OLD behavior. Use the cmake_policy command to
set it to OLD or NEW explicitly.
CMP0004
Libraries linked may not have leading or trailing
whitespace.
CMake versions 2.4 and below silently removed leading
and trailing whitespace from libraries linked with code
like
target_link_libraries(myexe " A ")
This could lead to subtle errors in user projects.
The OLD behavior for this policy is to silently remove
leading and trailing whitespace. The NEW behavior for
this policy is to diagnose the existence of such white-
space as an error. The setting for this policy used
when checking the library names is that in effect when
the target is created by an add_executable or
add_library command.
This policy was introduced in CMake version 2.6.0.
CMake version 2.8.6 warns when the policy is not set
and uses OLD behavior. Use the cmake_policy command to
set it to OLD or NEW explicitly.
CMP0005
Preprocessor definition values are now escaped automat-
ically.
This policy determines whether or not CMake should
cmake 2.8.6 Last change: June 17, 2014 5
User Commands cmakepolicies(1)
generate escaped preprocessor definition values added
via add_definitions. CMake versions 2.4 and below
assumed that only trivial values would be given for
macros in add_definitions calls. It did not attempt to
escape non-trivial values such as string literals in
generated build rules. CMake versions 2.6 and above
support escaping of most values, but cannot assume the
user has not added escapes already in an attempt to
work around limitations in earlier versions.
The OLD behavior for this policy is to place definition
values given to add_definitions directly in the gener-
ated build rules without attempting to escape anything.
The NEW behavior for this policy is to generate correct
escapes for all native build tools automatically. See
documentation of the COMPILE_DEFINITIONS target prop-
erty for limitations of the escaping implementation.
This policy was introduced in CMake version 2.6.0.
CMake version 2.8.6 warns when the policy is not set
and uses OLD behavior. Use the cmake_policy command to
set it to OLD or NEW explicitly.
CMP0006
Installing MACOSX_BUNDLE targets requires a BUNDLE DES-
TINATION.
This policy determines whether the install(TARGETS)
command must be given a BUNDLE DESTINATION when asked
to install a target with the MACOSX_BUNDLE property
set. CMake 2.4 and below did not distinguish applica-
tion bundles from normal executables when installing
targets. CMake 2.6 provides a BUNDLE option to the
install(TARGETS) command that specifies rules specific
to application bundles on the Mac. Projects should use
this option when installing a target with the
MACOSX_BUNDLE property set.
The OLD behavior for this policy is to fall back to the
RUNTIME DESTINATION if a BUNDLE DESTINATION is not
given. The NEW behavior for this policy is to produce
an error if a bundle target is installed without a BUN-
DLE DESTINATION.
This policy was introduced in CMake version 2.6.0.
CMake version 2.8.6 warns when the policy is not set
and uses OLD behavior. Use the cmake_policy command to
cmake 2.8.6 Last change: June 17, 2014 6
User Commands cmakepolicies(1)
set it to OLD or NEW explicitly.
CMP0007
list command no longer ignores empty elements.
This policy determines whether the list command will
ignore empty elements in the list. CMake 2.4 and below
list commands ignored all empty elements in the list.
For example, a;b;;c would have length 3 and not 4. The
OLD behavior for this policy is to ignore empty list
elements. The NEW behavior for this policy is to cor-
rectly count empty elements in a list.
This policy was introduced in CMake version 2.6.0.
CMake version 2.8.6 warns when the policy is not set
and uses OLD behavior. Use the cmake_policy command to
set it to OLD or NEW explicitly.
CMP0008
Libraries linked by full-path must have a valid library
file name.
In CMake 2.4 and below it is possible to write code
like
target_link_libraries(myexe /full/path/to/somelib)
where "somelib" is supposed to be a valid library file
name such as "libsomelib.a" or "somelib.lib". For
Makefile generators this produces an error at build
time because the dependency on the full path cannot be
found. For VS IDE and Xcode generators this used to
work by accident because CMake would always split off
the library directory and ask the linker to search for
the library by name (-lsomelib or somelib.lib).
Despite the failure with Makefiles, some projects have
code like this and build only with VS and/or Xcode.
This version of CMake prefers to pass the full path
directly to the native build tool, which will fail in
this case because it does not name a valid library
file.
This policy determines what to do with full paths that
do not appear to name a valid library file. The OLD
behavior for this policy is to split the library name
from the path and ask the linker to search for it. The
NEW behavior for this policy is to trust the given path
cmake 2.8.6 Last change: June 17, 2014 7
User Commands cmakepolicies(1)
and pass it directly to the native build tool
unchanged.
This policy was introduced in CMake version 2.6.1.
CMake version 2.8.6 warns when the policy is not set
and uses OLD behavior. Use the cmake_policy command to
set it to OLD or NEW explicitly.
CMP0009
FILE GLOB_RECURSE calls should not follow symlinks by
default.
In CMake 2.6.1 and below, FILE GLOB_RECURSE calls would
follow through symlinks, sometimes coming up with unex-
pectedly large result sets because of symlinks to top
level directories that contain hundreds of thousands of
files.
This policy determines whether or not to follow sym-
links encountered during a FILE GLOB_RECURSE call. The
OLD behavior for this policy is to follow the symlinks.
The NEW behavior for this policy is not to follow the
symlinks by default, but only if FOLLOW_SYMLINKS is
given as an additional argument to the FILE command.
This policy was introduced in CMake version 2.6.2.
CMake version 2.8.6 warns when the policy is not set
and uses OLD behavior. Use the cmake_policy command to
set it to OLD or NEW explicitly.
CMP0010
Bad variable reference syntax is an error.
In CMake 2.6.2 and below, incorrect variable reference
syntax such as a missing close-brace ("${FOO") was
reported but did not stop processing of CMake code.
This policy determines whether a bad variable reference
is an error. The OLD behavior for this policy is to
warn about the error, leave the string untouched, and
continue. The NEW behavior for this policy is to report
an error.
This policy was introduced in CMake version 2.6.3.
CMake version 2.8.6 warns when the policy is not set
and uses OLD behavior. Use the cmake_policy command to
set it to OLD or NEW explicitly.
cmake 2.8.6 Last change: June 17, 2014 8
User Commands cmakepolicies(1)
CMP0011
Included scripts do automatic cmake_policy PUSH and
POP.
In CMake 2.6.2 and below, CMake Policy settings in
scripts loaded by the include() and find_package() com-
mands would affect the includer. Explicit invocations
of cmake_policy(PUSH) and cmake_policy(POP) were
required to isolate policy changes and protect the
includer. While some scripts intend to affect the
policies of their includer, most do not. In CMake
2.6.3 and above, include() and find_package() by
default PUSH and POP an entry on the policy stack
around an included script, but provide a NO_POL-
ICY_SCOPE option to disable it. This policy determines
whether or not to imply NO_POLICY_SCOPE for compatibil-
ity. The OLD behavior for this policy is to imply
NO_POLICY_SCOPE for include() and find_package() com-
mands. The NEW behavior for this policy is to allow
the commands to do their default cmake_policy PUSH and
POP.
This policy was introduced in CMake version 2.6.3.
CMake version 2.8.6 warns when the policy is not set
and uses OLD behavior. Use the cmake_policy command to
set it to OLD or NEW explicitly.
CMP0012
if() recognizes numbers and boolean constants.
In CMake versions 2.6.4 and lower the if() command
implicitly dereferenced arguments corresponding to
variables, even those named like numbers or boolean
constants, except for 0 and 1. Numbers and boolean
constants such as true, false, yes, no, on, off, y, n,
notfound, ignore (all case insensitive) were recognized
in some cases but not all. For example, the code
"if(TRUE)" might have evaluated as false. Numbers such
as 2 were recognized only in boolean expressions like
"if(NOT 2)" (leading to false) but not as a sin-
gle-argument like "if(2)" (also leading to false).
Later versions of CMake prefer to treat numbers and
boolean constants literally, so they should not be used
as variable names.
The OLD behavior for this policy is to implicitly
dereference variables named like numbers and boolean
constants. The NEW behavior for this policy is to rec-
ognize numbers and boolean constants without
cmake 2.8.6 Last change: June 17, 2014 9
User Commands cmakepolicies(1)
dereferencing variables with such names.
This policy was introduced in CMake version 2.8.0.
CMake version 2.8.6 warns when the policy is not set
and uses OLD behavior. Use the cmake_policy command to
set it to OLD or NEW explicitly.
CMP0013
Duplicate binary directories are not allowed.
CMake 2.6.3 and below silently permitted add_subdirec-
tory() calls to create the same binary directory multi-
ple times. During build system generation files would
be written and then overwritten in the build tree and
could lead to strange behavior. CMake 2.6.4 and above
explicitly detect duplicate binary directories. CMake
2.6.4 always considers this case an error. In CMake
2.8.0 and above this policy determines whether or not
the case is an error. The OLD behavior for this policy
is to allow duplicate binary directories. The NEW
behavior for this policy is to disallow duplicate
binary directories with an error.
This policy was introduced in CMake version 2.8.0.
CMake version 2.8.6 warns when the policy is not set
and uses OLD behavior. Use the cmake_policy command to
set it to OLD or NEW explicitly.
CMP0014
Input directories must have CMakeLists.txt.
CMake versions before 2.8 silently ignored missing
CMakeLists.txt files in directories referenced by
add_subdirectory() or subdirs(), treating them as if
present but empty. In CMake 2.8.0 and above this pol-
icy determines whether or not the case is an error.
The OLD behavior for this policy is to silently ignore
the problem. The NEW behavior for this policy is to
report an error.
This policy was introduced in CMake version 2.8.0.
CMake version 2.8.6 warns when the policy is not set
and uses OLD behavior. Use the cmake_policy command to
set it to OLD or NEW explicitly.
CMP0015
cmake 2.8.6 Last change: June 17, 2014 10
User Commands cmakepolicies(1)
link_directories() treats paths relative to the source
dir.
In CMake 2.8.0 and lower the link_directories() command
passed relative paths unchanged to the linker. In
CMake 2.8.1 and above the link_directories() command
prefers to interpret relative paths with respect to
CMAKE_CURRENT_SOURCE_DIR, which is consistent with
include_directories() and other commands. The OLD
behavior for this policy is to use relative paths ver-
batim in the linker command. The NEW behavior for this
policy is to convert relative paths to absolute paths
by appending the relative path to CMAKE_CUR-
RENT_SOURCE_DIR.
This policy was introduced in CMake version 2.8.1.
CMake version 2.8.6 warns when the policy is not set
and uses OLD behavior. Use the cmake_policy command to
set it to OLD or NEW explicitly.
CMP0016
target_link_libraries() reports error if only argument
is not a target.
In CMake 2.8.2 and lower the target_link_libraries()
command silently ignored if it was called with only one
argument, and this argument wasn't a valid target. In
CMake 2.8.3 and above it reports an error in this case.
This policy was introduced in CMake version 2.8.3.
CMake version 2.8.6 warns when the policy is not set
and uses OLD behavior. Use the cmake_policy command to
set it to OLD or NEW explicitly.
CMP0017
Prefer files from the CMake module directory when
including from there.
Starting with CMake 2.8.4, if a cmake-module shipped
with CMake (i.e. located in the CMake module directory)
calls include() or find_package(), the files located in
the the CMake module directory are preferred over the
files in CMAKE_MODULE_PATH. This makes sure that the
modules belonging to CMake always get those files
included which they expect, and against which they were
developed and tested. In call other cases, the files
found in CMAKE_MODULE_PATH still take precedence over
the ones in the CMake module directory. The OLD
cmake 2.8.6 Last change: June 17, 2014 11
User Commands cmakepolicies(1)
behaviour is to always prefer files from CMAKE_MOD-
ULE_PATH over files from the CMake modules directory.
This policy was introduced in CMake version 2.8.4.
CMake version 2.8.6 warns when the policy is not set
and uses OLD behavior. Use the cmake_policy command to
set it to OLD or NEW explicitly.
COPYRIGHT
Copyright 2000-2009 Kitware, Inc., Insight Software Consor-
tium. All rights reserved.
Redistribution and use in source and binary forms, with or
without modification, are permitted provided that the fol-
lowing conditions are met:
Redistributions of source code must retain the above copy-
right notice, this list of conditions and the following dis-
claimer.
Redistributions in binary form must reproduce the above
copyright notice, this list of conditions and the following
disclaimer in the documentation and/or other materials pro-
vided with the distribution.
Neither the names of Kitware, Inc., the Insight Software
Consortium, nor the names of their contributors may be used
to endorse or promote products derived from this software
without specific prior written permission.
THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CON-
TRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES,
INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CON-
TRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT
NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES;
LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFT-
WARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
cmake 2.8.6 Last change: June 17, 2014 12
User Commands cmakepolicies(1)
ATTRIBUTES
See attributes(5) for descriptions of the following
attributes:
+---------------+-----------------------+
|ATTRIBUTE TYPE | ATTRIBUTE VALUE |
+---------------+-----------------------+
|Availability | developer/build/cmake |
+---------------+-----------------------+
|Stability | Uncommitted |
+---------------+-----------------------+
SEE ALSO
ccmake(1), cpack(1), ctest(1), cmakecommands(1), cmakecom-
pat(1), cmakemodules(1),
The following resources are available to get help using
CMake:
Home Page
http://www.cmake.org
The primary starting point for learning about CMake.
Frequently Asked Questions
http://www.cmake.org/Wiki/CMake_FAQ
A Wiki is provided containing answers to frequently
asked questions.
Online Documentation
http://www.cmake.org/HTML/Documentation.html
Links to available documentation may be found on this
web page.
Mailing List
http://www.cmake.org/HTML/MailingLists.html
For help and discussion about using cmake, a mailing
list is provided at [email protected]. The list is mem-
ber-post-only but one may sign up on the CMake web
page. Please first read the full documentation at
http://www.cmake.org before posting questions to the
list.
cmake 2.8.6 Last change: June 17, 2014 13
User Commands cmakepolicies(1)
Summary of helpful links:
Home: http://www.cmake.org
Docs: http://www.cmake.org/HTML/Documentation.html
Mail: http://www.cmake.org/HTML/MailingLists.html
FAQ: http://www.cmake.org/Wiki/CMake_FAQ
NOTES
This software was built from source available at
https://java.net/projects/solaris-userland. The original
community source was downloaded from
http://www.cmake.org/files/v2.8/cmake-2.8.6.tar.gz
Further information about this software can be found on the
open source community website at http://www.cmake.org/.
cmake 2.8.6 Last change: June 17, 2014 14