462 lines
22 KiB
Plaintext
462 lines
22 KiB
Plaintext
cmake version 2.8.0
|
|
------------------------------------------------------------------------------
|
|
Introduction
|
|
|
|
cmake-policies - Reference of CMake policies.
|
|
|
|
------------------------------------------------------------------------------
|
|
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 running 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 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_COMPATIBILITY 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_BACKWARDS_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 written for CMake 2.4 and
|
|
below.
|
|
|
|
This policy was introduced in CMake version 2.6.0. CMake version
|
|
2.8.0 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 global
|
|
property ALLOW_DUPLICATE_CUSTOM_TARGETS with a Makefiles generator).
|
|
|
|
This policy was introduced in CMake version 2.6.0. CMake version
|
|
2.8.0 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 performed 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 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 previously. When
|
|
this policy is set to NEW, CMake will produce a link line such as
|
|
|
|
... /path/to/libA.so -lB ...
|
|
|
|
which more accurately matches what the project specified.
|
|
|
|
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)
|
|
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.0 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 whitespace 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.0 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 automatically.
|
|
|
|
This policy determines whether or not CMake should 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 generated 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 property for
|
|
limitations of the escaping implementation.
|
|
|
|
This policy was introduced in CMake version 2.6.0. CMake version
|
|
2.8.0 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 DESTINATION.
|
|
|
|
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
|
|
application 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 BUNDLE DESTINATION.
|
|
|
|
This policy was introduced in CMake version 2.6.0. CMake version
|
|
2.8.0 warns when the policy is not set and uses OLD behavior. Use the
|
|
cmake_policy command to 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 correctly count
|
|
empty elements in a list.
|
|
|
|
This policy was introduced in CMake version 2.6.0. CMake version
|
|
2.8.0 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 and
|
|
pass it directly to the native build tool unchanged.
|
|
|
|
This policy was introduced in CMake version 2.6.1. CMake version
|
|
2.8.0 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 unexpectedly 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 symlinks 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.0 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.0 warns when the policy is not set and uses OLD behavior. Use the
|
|
cmake_policy command to set it to OLD or NEW explicitly.
|
|
|
|
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() commands 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_POLICY_SCOPE option to disable it. This
|
|
policy determines whether or not to imply NO_POLICY_SCOPE for
|
|
compatibility. The OLD behavior for this policy is to imply
|
|
NO_POLICY_SCOPE for include() and find_package() commands. 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.0 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 single-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 recognize numbers and boolean constants without
|
|
dereferencing variables with such names.
|
|
|
|
This policy was introduced in CMake version 2.8.0. CMake version
|
|
2.8.0 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_subdirectory() calls to
|
|
create the same binary directory multiple 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.0 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
|
|
policy 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.0 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 Consortium. All rights
|
|
reserved.
|
|
|
|
Redistribution and use in source and binary forms, with or without
|
|
modification, are permitted provided that the following conditions are met:
|
|
|
|
Redistributions of source code must retain the above copyright notice, this
|
|
list of conditions and the following disclaimer.
|
|
|
|
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 provided 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 CONTRIBUTORS "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 CONTRIBUTORS 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 SOFTWARE, EVEN IF ADVISED OF THE
|
|
POSSIBILITY OF SUCH DAMAGE.
|
|
|
|
------------------------------------------------------------------------------
|
|
See Also
|
|
|
|
.B ccmake(1), cpack(1), ctest(1), cmakecommands(1), cmakecompat(1),
|
|
cmakemodules(1), cmakeprops(1), cmakevars(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 cmake@cmake.org. The list is member-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.
|
|
|
|
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
|
|
|
|
|