Commit 07f3082d authored by Bartosz Kosiorek's avatar Bartosz Kosiorek

Help: Improve documentation links and formatting

parent db20cb2f
......@@ -11,14 +11,14 @@ Collects the names of all the source files in the specified directory
and stores the list in the ``<variable>`` provided. This command is
intended to be used by projects that use explicit template
instantiation. Template instantiation files can be stored in a
"Templates" subdirectory and collected automatically using this
``Templates`` subdirectory and collected automatically using this
command to avoid manually listing all instantiations.
It is tempting to use this command to avoid writing the list of source
files for a library or executable target. While this seems to work,
there is no way for CMake to generate a build system that knows when a
new source file has been added. Normally the generated build system
knows when it needs to rerun CMake because the CMakeLists.txt file is
knows when it needs to rerun CMake because the ``CMakeLists.txt`` file is
modified to add a new source. When the source is just added to the
directory without modifying this file, one would have to manually
rerun CMake to generate a build system incorporating the new file.
......@@ -9,7 +9,7 @@ Copy mesa headers for use in combination with system GL.
use_mangled_mesa(PATH_TO_MESA OUTPUT_DIRECTORY)
The path to mesa includes, should contain gl_mangle.h. The mesa
The path to mesa includes, should contain ``gl_mangle.h``. The mesa
headers are copied to the specified output directory. This allows
mangled mesa headers to override other GL headers by being added to
the include directory path earlier.
......@@ -7,25 +7,27 @@ 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:
versions newer than that specified. Use the :command:`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
where ``<major>.<minor>`` is the version of CMake you want to support
(such as ``3.14``). 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.
the project. See documentation of :command:`cmake_minimum_required` for
details.
Note that the command invocation must appear in the CMakeLists.txt
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.
the :command:`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.
``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
The 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
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
and the :command:`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
|release| warns when the policy is not set and uses OLD behavior. Use
the cmake_policy command to set it to OLD or NEW explicitly.
|release| warns when the policy is not set and uses ``OLD`` behavior. Use
the :command:`cmake_policy` command to set it to ``OLD`` or ``NEW`` explicitly.
.. include:: DEPRECATED.txt
......@@ -3,8 +3,8 @@ 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
Targets names created with :command:`add_executable`, :command:`add_library`, or
:command:`add_custom_target` are logical build target names. Logical target
names must be globally unique because:
::
......@@ -16,13 +16,13 @@ names must be globally unique because:
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
:prop_tgt:`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).
property :prop_gbl:`ALLOW_DUPLICATE_CUSTOM_TARGETS` with a Makefiles generator).
This policy was introduced in CMake version 2.6.0. CMake version
|release| warns when the policy is not set and uses OLD behavior. Use
the cmake_policy command to set it to OLD or NEW explicitly.
|release| warns when the policy is not set and uses ``OLD`` behavior. Use
the :command:`cmake_policy` command to set it to ``OLD`` or ``NEW`` explicitly.
.. include:: DEPRECATED.txt
......@@ -37,7 +37,7 @@ 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
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
......@@ -45,9 +45,9 @@ 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
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
needed for their own libraries. When this policy is set to ``OLD``, CMake
will produce a link line such as
::
......@@ -98,7 +98,7 @@ 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
|release| warns when the policy is not set and uses OLD behavior. Use
the cmake_policy command to set it to OLD or NEW explicitly.
|release| warns when the policy is not set and uses ``OLD`` behavior. Use
the :command:`cmake_policy` command to set it to ``OLD`` or ``NEW`` explicitly.
.. include:: DEPRECATED.txt
......@@ -12,14 +12,15 @@ whitespace from libraries linked with code like
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 ``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.
target is created by an :command:`add_executable` or :command:`add_library`
command.
This policy was introduced in CMake version 2.6.0. CMake version
|release| warns when the policy is not set and uses OLD behavior. Use
the cmake_policy command to set it to OLD or NEW explicitly.
|release| warns when the policy is not set and uses ``OLD`` behavior. Use
the :command:`cmake_policy` command to set it to ``OLD`` or ``NEW`` explicitly.
.. include:: DEPRECATED.txt
......@@ -12,15 +12,15 @@ 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
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
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
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
|release| warns when the policy is not set and uses OLD behavior. Use
the cmake_policy command to set it to OLD or NEW explicitly.
|release| warns when the policy is not set and uses ``OLD`` behavior. Use
the :command:`cmake_policy` command to set it to ``OLD`` or ``NEW`` explicitly.
.. include:: DEPRECATED.txt
CMP0006
-------
Installing MACOSX_BUNDLE targets requires a BUNDLE DESTINATION.
Installing :prop_tgt:`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
This policy determines whether the :command:`install(TARGETS)` command must be
given a ``BUNDLE DESTINATION`` when asked to install a target with the
:prop_tgt:`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.
CMake 2.6 provides a ``BUNDLE`` option to the :command:`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.
:prop_tgt:`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.
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
|release| warns when the policy is not set and uses OLD behavior. Use
the cmake_policy command to set it to OLD or NEW explicitly.
|release| warns when the policy is not set and uses ``OLD`` behavior. Use
the :command:`cmake_policy` command to set it to ``OLD`` or ``NEW`` explicitly.
.. include:: DEPRECATED.txt
......@@ -5,13 +5,13 @@ 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 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
|release| warns when the policy is not set and uses OLD behavior. Use
the cmake_policy command to set it to OLD or NEW explicitly.
|release| warns when the policy is not set and uses ``OLD`` behavior. Use
the :command:`cmake_policy` command to set it to ``OLD`` or ``NEW`` explicitly.
.. include:: DEPRECATED.txt
......@@ -9,26 +9,26 @@ 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
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
(``-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
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
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
|release| warns when the policy is not set and uses OLD behavior. Use
the cmake_policy command to set it to OLD or NEW explicitly.
|release| warns when the policy is not set and uses ``OLD`` behavior. Use
the :command:`cmake_policy` command to set it to ``OLD`` or ``NEW`` explicitly.
.. include:: DEPRECATED.txt
......@@ -3,19 +3,19 @@ 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
In CMake 2.6.1 and below, :command:`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.
during a :command:`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
|release| warns when the policy is not set and uses OLD behavior. Use
the cmake_policy command to set it to OLD or NEW explicitly.
|release| warns when the policy is not set and uses ``OLD`` behavior. Use
the :command:`cmake_policy` command to set it to ``OLD`` or ``NEW`` explicitly.
.. include:: DEPRECATED.txt
......@@ -4,17 +4,17 @@ 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
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
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.
The ``NEW`` behavior for this policy is to report an error.
If :policy:`CMP0053` is set to ``NEW``, this policy has no effect
and is treated as always being ``NEW``.
This policy was introduced in CMake version 2.6.3. CMake version
|release| warns when the policy is not set and uses OLD behavior. Use
the cmake_policy command to set it to OLD or NEW explicitly.
|release| warns when the policy is not set and uses ``OLD`` behavior. Use
the :command:`cmake_policy` command to set it to ``OLD`` or ``NEW`` explicitly.
.. include:: DEPRECATED.txt
CMP0011
-------
Included scripts do automatic cmake_policy PUSH and POP.
Included scripts do automatic :command:`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.
the :command:`include` and :command:`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, :command:`include` and
:command:`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 :command:`include` and :command:`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
|release| warns when the policy is not set and uses OLD behavior. Use
the cmake_policy command to set it to OLD or NEW explicitly.
|release| warns when the policy is not set and uses ``OLD`` behavior. Use
the :command:`cmake_policy` command to set it to ``OLD`` or ``NEW`` explicitly.
.. include:: DEPRECATED.txt
CMP0012
-------
if() recognizes numbers and boolean constants.
:command:`if` recognizes numbers and boolean constants.
In CMake versions 2.6.4 and lower the if() command implicitly
In CMake versions 2.6.4 and lower the :command:`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
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
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
|release| warns when the policy is not set and uses OLD behavior. Use
the cmake_policy command to set it to OLD or NEW explicitly.
|release| warns when the policy is not set and uses ``OLD`` behavior. Use
the :command:`cmake_policy` command to set it to ``OLD`` or ``NEW`` explicitly.
.. include:: DEPRECATED.txt
......@@ -9,13 +9,13 @@ 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
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
|release| warns when the policy is not set and uses OLD behavior. Use
the cmake_policy command to set it to OLD or NEW explicitly.
|release| warns when the policy is not set and uses ``OLD`` behavior. Use
the :command:`cmake_policy` command to set it to ``OLD`` or ``NEW`` explicitly.
.. include:: DEPRECATED.txt
CMP0014
-------
Input directories must have CMakeLists.txt.
Input directories must have ``CMakeLists.txt``.
CMake versions before 2.8 silently ignored missing 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
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
|release| warns when the policy is not set and uses OLD behavior. Use
the cmake_policy command to set it to OLD or NEW explicitly.
|release| warns when the policy is not set and uses ``OLD`` behavior. Use
the :command:`cmake_policy` command to set it to ``OLD`` or ``NEW`` explicitly.
.. include:: DEPRECATED.txt
......@@ -7,13 +7,13 @@ 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
include_directories() and other commands. The ``OLD`` behavior for this
policy is to use relative paths verbatim in the linker command. The
NEW behavior for this policy is to convert relative paths to absolute
``NEW`` behavior for this policy is to convert relative paths to absolute
paths by appending the relative path to CMAKE_CURRENT_SOURCE_DIR.
This policy was introduced in CMake version 2.8.1. CMake version
|release| warns when the policy is not set and uses OLD behavior. Use
the cmake_policy command to set it to OLD or NEW explicitly.
|release| warns when the policy is not set and uses ``OLD`` behavior. Use
the :command:`cmake_policy` command to set it to ``OLD`` or ``NEW`` explicitly.
.. include:: DEPRECATED.txt
CMP0016
-------
target_link_libraries() reports error if its only argument is not a target.
:command:`target_link_libraries` reports error if its only argument
is not a target.
In CMake 2.8.2 and lower the target_link_libraries() command silently
In CMake 2.8.2 and lower the :command:`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
|release| warns when the policy is not set and uses OLD behavior. Use
the cmake_policy command to set it to OLD or NEW explicitly.
|release| warns when the policy is not set and uses ``OLD`` behavior. Use
the :command:`cmake_policy` command to set it to ``OLD`` or ``NEW`` explicitly.
.. include:: DEPRECATED.txt
......@@ -4,18 +4,18 @@ 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
located in the CMake module directory) calls :command:`include` or
find_package(), the files located in 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
preferred over the files in :variable:`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 all
other cases, the files found in CMAKE_MODULE_PATH still take
other cases, the files found in :variable:`CMAKE_MODULE_PATH` still take
precedence over the ones in the CMake module directory. The OLD
behavior is to always prefer files from CMAKE_MODULE_PATH over files
from the CMake modules directory.
This policy was introduced in CMake version 2.8.4. CMake version
|release| warns when the policy is not set and uses OLD behavior. Use
the cmake_policy command to set it to OLD or NEW explicitly.
|release| warns when the policy is not set and uses ``OLD`` behavior. Use
the :command:`cmake_policy` command to set it to ``OLD`` or ``NEW`` explicitly.
.. include:: DEPRECATED.txt
CMP0018
-------
Ignore CMAKE_SHARED_LIBRARY_<Lang>_FLAGS variable.
Ignore ``CMAKE_SHARED_LIBRARY_<Lang>_FLAGS`` variable.
CMake 2.8.8 and lower compiled sources in SHARED and MODULE libraries
using the value of the undocumented CMAKE_SHARED_LIBRARY_<Lang>_FLAGS
CMake 2.8.8 and lower compiled sources in ``SHARED`` and ``MODULE`` libraries
using the value of the undocumented ``CMAKE_SHARED_LIBRARY_<Lang>_FLAGS``
platform variable. The variable contained platform-specific flags
needed to compile objects for shared libraries. Typically it included
a flag such as -fPIC for position independent code but also included
a flag such as ``-fPIC`` for position independent code but also included
other flags needed on certain platforms. CMake 2.8.9 and higher
prefer instead to use the POSITION_INDEPENDENT_CODE target property to
determine what targets should be position independent, and new
prefer instead to use the :prop_tgt:`POSITION_INDEPENDENT_CODE` target
property to determine what targets should be position independent, and new
undocumented platform variables to select flags while ignoring
CMAKE_SHARED_LIBRARY_<Lang>_FLAGS completely.
``CMAKE_SHARED_LIBRARY_<Lang>_FLAGS`` completely.
The default for either approach produces identical compilation flags,
but if a project modifies CMAKE_SHARED_LIBRARY_<Lang>_FLAGS from its
but if a project modifies ``CMAKE_SHARED_LIBRARY_<Lang>_FLAGS`` from its
original value this policy determines which approach to use.
The OLD behavior for this policy is to ignore the
POSITION_INDEPENDENT_CODE property for all targets and use the
modified value of CMAKE_SHARED_LIBRARY_<Lang>_FLAGS for SHARED and
MODULE libraries.
The ``OLD`` behavior for this policy is to ignore the
:prop_tgt:`POSITION_INDEPENDENT_CODE` property for all targets and use the
modified value of ``CMAKE_SHARED_LIBRARY_<Lang>_FLAGS`` for ``SHARED`` and
``MODULE`` libraries.
The NEW behavior for this policy is to ignore
CMAKE_SHARED_LIBRARY_<Lang>_FLAGS whether it is modified or not and
honor the POSITION_INDEPENDENT_CODE target property.
The ``NEW`` behavior for this policy is to ignore
``CMAKE_SHARED_LIBRARY_<Lang>_FLAGS`` whether it is modified or not and
honor the :prop_tgt:`POSITION_INDEPENDENT_CODE` target property.
This policy was introduced in CMake version 2.8.9. CMake version
|release| warns when the policy is not set and uses OLD behavior. Use
the cmake_policy command to set it to OLD or NEW explicitly.
|release| warns when the policy is not set and uses ``OLD`` behavior. Use
the :command:`cmake_policy` command to set it to ``OLD`` or ``NEW``
explicitly.
.. include:: DEPRECATED.txt
......@@ -11,12 +11,12 @@ CMake versions because all variable references are now normally
evaluated during CMake language processing. CMake 2.8.11 and higher
prefer to skip the extra evaluation.
The OLD behavior for this policy is to re-evaluate the values for
strict compatibility. The NEW behavior for this policy is to leave
The ``OLD`` behavior for this policy is to re-evaluate the values for
strict compatibility. The ``NEW`` behavior for this policy is to leave
the values untouched.
This policy was introduced in CMake version 2.8.11. CMake version
|release| warns when the policy is not set and uses OLD behavior. Use
the cmake_policy command to set it to OLD or NEW explicitly.
|release| warns when the policy is not set and uses ``OLD`` behavior. Use
the :command:`cmake_policy` command to set it to ``OLD`` or ``NEW`` explicitly.
.. include:: DEPRECATED.txt
CMP0020
-------
Automatically link Qt executables to qtmain target on Windows.
Automatically link Qt executables to ``qtmain`` target on Windows.
CMake 2.8.10 and lower required users of Qt to always specify a link
dependency to the qtmain.lib static library manually on Windows.
dependency to the ``qtmain.lib`` static library manually on Windows.
CMake 2.8.11 gained the ability to evaluate generator expressions
while determining the link dependencies from IMPORTED targets. This
while determining the link dependencies from ``IMPORTED`` targets. This
allows CMake itself to automatically link executables which link to Qt
to the qtmain.lib library when using IMPORTED Qt targets. For
applications already linking to qtmain.lib, this should have little
to the ``qtmain.lib`` library when using ``IMPORTED`` Qt targets. For
applications already linking to ``qtmain.lib``, this should have little
impact. For applications which supply their own alternative WinMain
implementation and for applications which use the QAxServer library,
this automatic linking will need to be disabled as per the
documentation.
The OLD behavior for this policy is not to link executables to
qtmain.lib automatically when they link to the QtCore IMPORTED target.
The NEW behavior for this policy is to link executables to qtmain.lib
automatically when they link to QtCore IMPORTED target.
The ``OLD`` behavior for this policy is not to link executables to
``qtmain.lib`` automatically when they link to the QtCore ``IMPORTED`` target.
The ``NEW`` behavior for this policy is to link executables to ``qtmain.lib``
automatically when they link to QtCore ``IMPORTED`` target.
This policy was introduced in CMake version 2.8.11. CMake version
|release| warns when the policy is not set and uses OLD behavior. Use
the cmake_policy command to set it to OLD or NEW explicitly.
|release| warns when the policy is not set and uses ``OLD`` behavior. Use
the :command:`cmake_policy` command to set it to ``OLD`` or ``NEW`` explicitly.
.. include:: DEPRECATED.txt
CMP0021
-------
Fatal error on relative paths in INCLUDE_DIRECTORIES target property.
Fatal error on relative paths in :prop_tgt:`INCLUDE_DIRECTORIES` target
property.
CMake 2.8.10.2 and lower allowed the INCLUDE_DIRECTORIES target
CMake 2.8.10.2 and lower allowed the :prop_tgt:`INCLUDE_DIRECTORIES` target
property to contain relative paths. The base path for such relative
entries is not well defined. CMake 2.8.12 issues a FATAL_ERROR if the
INCLUDE_DIRECTORIES property contains a relative path.
entries is not well defined. CMake 2.8.12 issues a ``FATAL_ERROR`` if the
:prop_tgt:`INCLUDE_DIRECTORIES` property contains a relative path.
The OLD behavior for this policy is not to warn about relative paths
in the INCLUDE_DIRECTORIES target property. The NEW behavior for this
policy is to issue a FATAL_ERROR if INCLUDE_DIRECTORIES contains a
The ``OLD`` behavior for this policy is not to warn about relative paths
in the ``INCLUDE_DIRECTORIES`` target property. The ``NEW`` behavior for this
policy is to issue a ``FATAL_ERROR`` if ``INCLUDE_DIRECTORIES`` contains a
relative path.
This policy was introduced in CMake version 2.8.12. CMake version
|release| warns when the policy is not set and uses OLD behavior. Use
the cmake_policy command to set it to OLD or NEW explicitly.
|release| warns when the policy is not set and uses ``OLD`` behavior. Use
the :command:`cmake_policy` command to set it to ``OLD`` or ``NEW`` explicitly.
.. include:: DEPRECATED.txt
CMP0022
-------
INTERFACE_LINK_LIBRARIES defines the link interface.
:prop_tgt:`INTERFACE_LINK_LIBRARIES` defines the link interface.
CMake 2.8.11 constructed the 'link interface' of a target from
properties matching ``(IMPORTED_)?LINK_INTERFACE_LIBRARIES(_<CONFIG>)?``.
The modern way to specify config-sensitive content is to use generator
expressions and the ``IMPORTED_`` prefix makes uniform processing of the
link interface with generator expressions impossible. The
INTERFACE_LINK_LIBRARIES target property was introduced as a
:prop_tgt:`INTERFACE_LINK_LIBRARIES` target property was introduced as a
replacement in CMake 2.8.12. This new property is named consistently
with the INTERFACE_COMPILE_DEFINITIONS, INTERFACE_INCLUDE_DIRECTORIES
and INTERFACE_COMPILE_OPTIONS properties. For in-build targets, CMake
with the ``INTERFACE_COMPILE_DEFINITIONS``, ``INTERFACE_INCLUDE_DIRECTORIES``
and ``INTERFACE_COMPILE_OPTIONS`` properties. For in-build targets, CMake
will use the INTERFACE_LINK_LIBRARIES property as the source of the
link interface only if policy CMP0022 is NEW. When exporting a target
which has this policy set to NEW, only the INTERFACE_LINK_LIBRARIES
property will be processed and generated for the IMPORTED target by
default. A new option to the install(EXPORT) and export commands
link interface only if policy ``CMP0022`` is ``NEW``. When exporting a target
which has this policy set to ``NEW``, only the :prop_tgt:`INTERFACE_LINK_LIBRARIES`
property will be processed and generated for the ``IMPORTED`` target by
default. A new option to the :command:`install(EXPORT)` and export commands
allows export of the old-style properties for compatibility with
downstream users of CMake versions older than 2.8.12. The
target_link_libraries command will no longer populate the properties
matching LINK_INTERFACE_LIBRARIES(_<CONFIG>)? if this policy is NEW.
:command:`target_link_libraries` command will no longer populate the properties
matching ``LINK_INTERFACE_LIBRARIES(_<CONFIG>)?`` if this policy is ``NEW``.
Warning-free future-compatible code which works with CMake 2.8.7 onwards
can be written by using the ``LINK_PRIVATE`` and ``LINK_PUBLIC`` keywords
of :command:`target_link_libraries`.
The OLD behavior for this policy is to ignore the
INTERFACE_LINK_LIBRARIES property for in-build targets. The NEW
behavior for this policy is to use the INTERFACE_LINK_LIBRARIES
The ``OLD`` behavior for this policy is to ignore the
:prop_tgt:`INTERFACE_LINK_LIBRARIES` property for in-build targets.
The ``NEW`` behavior for this policy is to use the ``INTERFACE_LINK_LIBRARIES``
property for in-build targets, and ignore the old properties matching
``(IMPORTED_)?LINK_INTERFACE_LIBRARIES(_<CONFIG>)?``.
This policy was introduced in CMake version 2.8.12. CMake version
|release| warns when the policy is not set and uses OLD behavior. Use
the cmake_policy command to set it to OLD or NEW explicitly.
|release| warns when the policy is not set and uses ``OLD`` behavior. Use
the :command:`cmake_policy` command to set it to ``OLD`` or ``NEW`` explicitly.
.. include:: DEPRECATED.txt