diff options
Diffstat (limited to 'Help/policy')
60 files changed, 546 insertions, 345 deletions
diff --git a/Help/policy/CMP0000.rst b/Help/policy/CMP0000.rst index 97ea633b2..aecfa7187 100644 --- a/Help/policy/CMP0000.rst +++ b/Help/policy/CMP0000.rst @@ -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. diff --git a/Help/policy/CMP0001.rst b/Help/policy/CMP0001.rst index 09ad38702..6fa64d983 100644 --- a/Help/policy/CMP0001.rst +++ b/Help/policy/CMP0001.rst @@ -1,21 +1,21 @@ 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 diff --git a/Help/policy/CMP0002.rst b/Help/policy/CMP0002.rst index 7cc53efa1..dc68d5180 100644 --- a/Help/policy/CMP0002.rst +++ b/Help/policy/CMP0002.rst @@ -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 diff --git a/Help/policy/CMP0003.rst b/Help/policy/CMP0003.rst index 16b045165..dd90883dc 100644 --- a/Help/policy/CMP0003.rst +++ b/Help/policy/CMP0003.rst @@ -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 diff --git a/Help/policy/CMP0004.rst b/Help/policy/CMP0004.rst index 55da4d293..be6d3079b 100644 --- a/Help/policy/CMP0004.rst +++ b/Help/policy/CMP0004.rst @@ -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 diff --git a/Help/policy/CMP0005.rst b/Help/policy/CMP0005.rst index 66d125fb7..59567d56e 100644 --- a/Help/policy/CMP0005.rst +++ b/Help/policy/CMP0005.rst @@ -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 diff --git a/Help/policy/CMP0006.rst b/Help/policy/CMP0006.rst index d1b9ece7f..181958b39 100644 --- a/Help/policy/CMP0006.rst +++ b/Help/policy/CMP0006.rst @@ -1,24 +1,24 @@ 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 diff --git a/Help/policy/CMP0007.rst b/Help/policy/CMP0007.rst index 39276457a..1006ed33a 100644 --- a/Help/policy/CMP0007.rst +++ b/Help/policy/CMP0007.rst @@ -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 diff --git a/Help/policy/CMP0008.rst b/Help/policy/CMP0008.rst index f1e2ddde5..18ede821c 100644 --- a/Help/policy/CMP0008.rst +++ b/Help/policy/CMP0008.rst @@ -9,26 +9,27 @@ 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 +path cannot be found. For :ref:`Visual Studio Generators` IDE +and :generator:`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. +(``-lsomelib`` or ``somelib.lib``). Despite the failure with Makefiles, some +projects have code like this and build only with Visual Studio 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 diff --git a/Help/policy/CMP0009.rst b/Help/policy/CMP0009.rst index 44baeb449..27cfde0db 100644 --- a/Help/policy/CMP0009.rst +++ b/Help/policy/CMP0009.rst @@ -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 diff --git a/Help/policy/CMP0010.rst b/Help/policy/CMP0010.rst index 344d70475..cfae4982a 100644 --- a/Help/policy/CMP0010.rst +++ b/Help/policy/CMP0010.rst @@ -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 diff --git a/Help/policy/CMP0011.rst b/Help/policy/CMP0011.rst index d281e0ef7..257415c26 100644 --- a/Help/policy/CMP0011.rst +++ b/Help/policy/CMP0011.rst @@ -1,24 +1,25 @@ 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 diff --git a/Help/policy/CMP0012.rst b/Help/policy/CMP0012.rst index 85d64f4d4..17ec8d33d 100644 --- a/Help/policy/CMP0012.rst +++ b/Help/policy/CMP0012.rst @@ -1,27 +1,28 @@ 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 diff --git a/Help/policy/CMP0013.rst b/Help/policy/CMP0013.rst index 2fabb8920..dbd67a177 100644 --- a/Help/policy/CMP0013.rst +++ b/Help/policy/CMP0013.rst @@ -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 diff --git a/Help/policy/CMP0014.rst b/Help/policy/CMP0014.rst index f1f7b77b8..331dde5ef 100644 --- a/Help/policy/CMP0014.rst +++ b/Help/policy/CMP0014.rst @@ -1,17 +1,17 @@ CMP0014 ------- -Input directories must have CMakeLists.txt. +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(), +CMake versions before 2.8 silently ignored missing ``CMakeLists.txt`` +files in directories referenced by :command:`add_subdirectory` or :command:`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. +:command:`cmake_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 diff --git a/Help/policy/CMP0015.rst b/Help/policy/CMP0015.rst index 9a48e3dac..90d520334 100644 --- a/Help/policy/CMP0015.rst +++ b/Help/policy/CMP0015.rst @@ -1,19 +1,19 @@ CMP0015 ------- -link_directories() treats paths relative to the source dir. + :command:`link_directories` treats paths relative to the source dir. -In CMake 2.8.0 and lower the link_directories() command passed +In CMake 2.8.0 and lower the :command:`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 verbatim 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_CURRENT_SOURCE_DIR. +:command:`link_directories` command prefers to interpret relative paths with +respect to ``CMAKE_CURRENT_SOURCE_DIR``, which is consistent with +:command:`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 +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 diff --git a/Help/policy/CMP0016.rst b/Help/policy/CMP0016.rst index cc898c8ca..026d02a9d 100644 --- a/Help/policy/CMP0016.rst +++ b/Help/policy/CMP0016.rst @@ -1,15 +1,16 @@ 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 diff --git a/Help/policy/CMP0017.rst b/Help/policy/CMP0017.rst index 9f0f0380f..ca4664eed 100644 --- a/Help/policy/CMP0017.rst +++ b/Help/policy/CMP0017.rst @@ -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 -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 +located in the CMake module directory) calls :command:`include` or +:command:`find_package`, the files located in the CMake module directory are +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 -precedence over the ones in the CMake module directory. The OLD +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 diff --git a/Help/policy/CMP0018.rst b/Help/policy/CMP0018.rst index a3a7a12bd..624840678 100644 --- a/Help/policy/CMP0018.rst +++ b/Help/policy/CMP0018.rst @@ -1,34 +1,35 @@ 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 diff --git a/Help/policy/CMP0019.rst b/Help/policy/CMP0019.rst index 2e3557d32..682dcdf86 100644 --- a/Help/policy/CMP0019.rst +++ b/Help/policy/CMP0019.rst @@ -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 diff --git a/Help/policy/CMP0020.rst b/Help/policy/CMP0020.rst index 75ca9deb2..6d27684f2 100644 --- a/Help/policy/CMP0020.rst +++ b/Help/policy/CMP0020.rst @@ -1,27 +1,27 @@ 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 diff --git a/Help/policy/CMP0021.rst b/Help/policy/CMP0021.rst index 3a792ca14..937b106eb 100644 --- a/Help/policy/CMP0021.rst +++ b/Help/policy/CMP0021.rst @@ -1,20 +1,21 @@ 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 diff --git a/Help/policy/CMP0022.rst b/Help/policy/CMP0022.rst index 579d09ac0..be60e375a 100644 --- a/Help/policy/CMP0022.rst +++ b/Help/policy/CMP0022.rst @@ -1,39 +1,39 @@ 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 diff --git a/Help/policy/CMP0023.rst b/Help/policy/CMP0023.rst index 76a4900b6..3c72c8195 100644 --- a/Help/policy/CMP0023.rst +++ b/Help/policy/CMP0023.rst @@ -1,15 +1,15 @@ CMP0023 ------- -Plain and keyword target_link_libraries signatures cannot be mixed. +Plain and keyword :command:`target_link_libraries` signatures cannot be mixed. -CMake 2.8.12 introduced the target_link_libraries signature using the -PUBLIC, PRIVATE, and INTERFACE keywords to generalize the LINK_PUBLIC -and LINK_PRIVATE keywords introduced in CMake 2.8.7. Use of -signatures with any of these keywords sets the link interface of a +CMake 2.8.12 introduced the :command:`target_link_libraries` signature using +the ``PUBLIC``, ``PRIVATE``, and ``INTERFACE`` keywords to generalize the +``LINK_PUBLIC`` and ``LINK_PRIVATE`` keywords introduced in CMake 2.8.7. +Use of signatures with any of these keywords sets the link interface of a target explicitly, even if empty. This produces confusing behavior when used in combination with the historical behavior of the plain -target_link_libraries signature. For example, consider the code: +:command:`target_link_libraries` signature. For example, consider the code: :: @@ -20,16 +20,16 @@ After the first line the link interface has not been set explicitly so CMake would use the link implementation, A, as the link interface. However, the second line sets the link interface to empty. In order to avoid this subtle behavior CMake now prefers to disallow mixing the -plain and keyword signatures of target_link_libraries for a single +plain and keyword signatures of :command:`target_link_libraries` for a single target. -The OLD behavior for this policy is to allow keyword and plain -target_link_libraries signatures to be mixed. The NEW behavior for +The ``OLD`` behavior for this policy is to allow keyword and plain +:command:`target_link_libraries` signatures to be mixed. The ``NEW`` behavior for this policy is to not to allow mixing of the keyword and plain signatures. 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 diff --git a/Help/policy/CMP0024.rst b/Help/policy/CMP0024.rst index 272a56c8d..6e24b0454 100644 --- a/Help/policy/CMP0024.rst +++ b/Help/policy/CMP0024.rst @@ -3,22 +3,23 @@ CMP0024 Disallow include export result. -CMake 2.8.12 and lower allowed use of the include() command with the -result of the export() command. This relies on the assumption that -the export() command has an immediate effect at configure-time during +CMake 2.8.12 and lower allowed use of the :command:`include` command with the +result of the :command:`export` command. This relies on the assumption that +the :command:`export` command has an immediate effect at configure-time during a cmake run. Certain properties of targets are not fully determined until later at generate-time, such as the link language and complete list of link libraries. Future refactoring will change the effect of -the export() command to be executed at generate-time. Use ALIAS +the :command:`export` command to be executed at generate-time. Use ``ALIAS`` targets instead in cases where the goal is to refer to targets by another name. -The OLD behavior for this policy is to allow including the result of -an export() command. The NEW behavior for this policy is not to -allow including the result of an export() command. +The ``OLD`` behavior for this policy is to allow including the result of +an :command:`export` command. The ``NEW`` behavior for this policy is not to +allow including the result of an :command:`export` command. This policy was introduced in CMake version 3.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 diff --git a/Help/policy/CMP0025.rst b/Help/policy/CMP0025.rst index 62dd50985..ba5e1e948 100644 --- a/Help/policy/CMP0025.rst +++ b/Help/policy/CMP0025.rst @@ -15,13 +15,13 @@ language ``<LANG>`` is enabled by the :command:`project` or :command:`enable_language` command. The policy must be set prior to the invocation of either command. -The OLD behavior for this policy is to use compiler id ``Clang``. The -NEW behavior for this policy is to use compiler id ``AppleClang``. +The ``OLD`` behavior for this policy is to use compiler id ``Clang``. The +``NEW`` behavior for this policy is to use compiler id ``AppleClang``. This policy was introduced in CMake version 3.0. Use the -:command:`cmake_policy` command to set this policy to OLD or NEW explicitly. -Unlike most policies, CMake version |release| does *not* warn -by default when this policy is not set and simply uses OLD behavior. +:command:`cmake_policy` command to set this policy to ``OLD`` or ``NEW`` +explicitly. Unlike most policies, CMake version |release| does *not* warn +by default when this policy is not set and simply uses ``OLD`` behavior. See documentation of the :variable:`CMAKE_POLICY_WARNING_CMP0025 <CMAKE_POLICY_WARNING_CMP<NNNN>>` variable to control the warning. diff --git a/Help/policy/CMP0026.rst b/Help/policy/CMP0026.rst index 3fe1374c8..3401d4a9a 100644 --- a/Help/policy/CMP0026.rst +++ b/Help/policy/CMP0026.rst @@ -3,26 +3,27 @@ CMP0026 Disallow use of the LOCATION property for build targets. -CMake 2.8.12 and lower allowed reading the LOCATION target +CMake 2.8.12 and lower allowed reading the :prop_tgt:`LOCATION` target property (and configuration-specific variants) to determine the eventual location of build targets. This relies on the assumption that all necessary information is available at configure-time to determine the final location and filename of the target. However, this property is not fully determined until later at -generate-time. At generate time, the $<TARGET_FILE> generator -expression can be used to determine the eventual LOCATION of a target +generate-time. At generate time, the ``$<TARGET_FILE>`` generator +expression can be used to determine the eventual :prop_tgt:`LOCATION` of a target output. -Code which reads the LOCATION target property can be ported to use the -$<TARGET_FILE> generator expression together with the file(GENERATE) -subcommand to generate a file containing the target location. +Code which reads the :prop_tgt:`LOCATION` target property can be ported to +use the ``$<TARGET_FILE>`` generator expression together with the +:command:`file(GENERATE)` subcommand to generate a file containing +the target location. -The OLD behavior for this policy is to allow reading the LOCATION -properties from build-targets. The NEW behavior for this policy is to -not to allow reading the LOCATION properties from build-targets. +The ``OLD`` behavior for this policy is to allow reading the :prop_tgt:`LOCATION` +properties from build-targets. The ``NEW`` behavior for this policy is to +not to allow reading the :prop_tgt:`LOCATION` properties from build-targets. This policy was introduced in CMake version 3.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 diff --git a/Help/policy/CMP0027.rst b/Help/policy/CMP0027.rst index 28913cee4..bf7b6a978 100644 --- a/Help/policy/CMP0027.rst +++ b/Help/policy/CMP0027.rst @@ -4,24 +4,24 @@ CMP0027 Conditionally linked imported targets with missing include directories. CMake 2.8.11 introduced introduced the concept of -INTERFACE_INCLUDE_DIRECTORIES, and a check at cmake time that the -entries in the INTERFACE_INCLUDE_DIRECTORIES of an IMPORTED target -actually exist. CMake 2.8.11 also introduced generator expression -support in the target_link_libraries command. However, if an imported -target is linked as a result of a generator expression evaluation, the -entries in the INTERFACE_INCLUDE_DIRECTORIES of that target were not +:prop_tgt:`INTERFACE_INCLUDE_DIRECTORIES`, and a check at cmake time that the +entries in the :prop_tgt:`INTERFACE_INCLUDE_DIRECTORIES` of an ``IMPORTED`` +target actually exist. CMake 2.8.11 also introduced generator expression +support in the :command:`target_link_libraries` command. However, if an +imported target is linked as a result of a generator expression evaluation, the +entries in the :prop_tgt:`INTERFACE_INCLUDE_DIRECTORIES` of that target were not checked for existence as they should be. -The OLD behavior of this policy is to report a warning if an entry in -the INTERFACE_INCLUDE_DIRECTORIES of a generator-expression -conditionally linked IMPORTED target does not exist. +The ``OLD`` behavior of this policy is to report a warning if an entry in +the :prop_tgt:`INTERFACE_INCLUDE_DIRECTORIES` of a generator-expression +conditionally linked ``IMPORTED`` target does not exist. -The NEW behavior of this policy is to report an error if an entry in -the INTERFACE_INCLUDE_DIRECTORIES of a generator-expression -conditionally linked IMPORTED target does not exist. +The ``NEW`` behavior of this policy is to report an error if an entry in +the :prop_tgt:`INTERFACE_INCLUDE_DIRECTORIES` of a generator-expression +conditionally linked ``IMPORTED`` target does not exist. This policy was introduced in CMake version 3.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 diff --git a/Help/policy/CMP0028.rst b/Help/policy/CMP0028.rst index be57125d4..ab3822993 100644 --- a/Help/policy/CMP0028.rst +++ b/Help/policy/CMP0028.rst @@ -1,25 +1,25 @@ CMP0028 ------- -Double colon in target name means ALIAS or IMPORTED target. +Double colon in target name means ``ALIAS`` or ``IMPORTED`` target. CMake 2.8.12 and lower allowed the use of targets and files with double -colons in target_link_libraries, with some buildsystem generators. +colons in :command:`target_link_libraries`, with some buildsystem generators. -The use of double-colons is a common pattern used to namespace IMPORTED -targets and ALIAS targets. When computing the link dependencies of a target, -the name of each dependency could either be a target, or a file on disk. -Previously, if a target was not found with a matching name, the name was -considered to refer to a file on disk. This can lead to confusing error +The use of double-colons is a common pattern used to namespace ``IMPORTED`` +targets and ``ALIAS`` targets. When computing the link dependencies of +a target, the name of each dependency could either be a target, or a file +on disk. Previously, if a target was not found with a matching name, the name +was considered to refer to a file on disk. This can lead to confusing error messages if there is a typo in what should be a target name. -The OLD behavior for this policy is to search for targets, then files on disk, -even if the search term contains double-colons. The NEW behavior for this -policy is to issue a FATAL_ERROR if a link dependency contains -double-colons but is not an IMPORTED target or an ALIAS target. +The ``OLD`` behavior for this policy is to search for targets, then files on +disk, even if the search term contains double-colons. The ``NEW`` behavior +for this policy is to issue a ``FATAL_ERROR`` if a link dependency contains +double-colons but is not an ``IMPORTED`` target or an ``ALIAS`` target. This policy was introduced in CMake version 3.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 diff --git a/Help/policy/CMP0037.rst b/Help/policy/CMP0037.rst index d1afeb7c2..9895fb0b4 100644 --- a/Help/policy/CMP0037.rst +++ b/Help/policy/CMP0037.rst @@ -10,24 +10,25 @@ as :manual:`cmake-generator-expressions(7)` and some diagnostics expect target names to match a restricted pattern. Target names may contain upper and lower case letters, numbers, the underscore -character (_), dot(.), plus(+) and minus(-). As a special case, ALIAS -targets and IMPORTED targets may contain two consecutive colons. +character (``_``), dot(``.``), plus(``+``) and minus(``-``). +As a special case, ``ALIAS`` and ``IMPORTED`` targets may contain +two consecutive colons. Target names reserved by one or more CMake generators are not allowed. -Among others these include "all", "clean", "help", and "install". +Among others these include ``all``, ``clean``, ``help``, and ``install``. -Target names associated with optional features, such as "test" and "package", -may also be reserved. CMake 3.10 and below always reserve them. CMake 3.11 -and above reserve them only when the corresponding feature is enabled -(e.g. by including the :module:`CTest` or :module:`CPack` modules). +Target names associated with optional features, such as ``test`` and +``package``, may also be reserved. CMake 3.10 and below always reserve them. +CMake 3.11 and above reserve them only when the corresponding feature is +enabled (e.g. by including the :module:`CTest` or :module:`CPack` modules). -The OLD behavior for this policy is to allow creating targets with +The ``OLD`` behavior for this policy is to allow creating targets with reserved names or which do not match the validity pattern. -The NEW behavior for this policy is to report an error +The ``NEW`` behavior for this policy is to report an error if an add_* command is used with an invalid target name. This policy was introduced in CMake version 3.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 diff --git a/Help/policy/CMP0038.rst b/Help/policy/CMP0038.rst index a306d90a9..7fb2209fa 100644 --- a/Help/policy/CMP0038.rst +++ b/Help/policy/CMP0038.rst @@ -7,12 +7,12 @@ CMake 2.8.12 and lower allowed a build target to link to itself directly with a :command:`target_link_libraries` call. This is an indicator of a bug in user code. -The OLD behavior for this policy is to ignore targets which list themselves -in their own link implementation. The NEW behavior for this policy is to +The ``OLD`` behavior for this policy is to ignore targets which list themselves +in their own link implementation. The ``NEW`` behavior for this policy is to report an error if a target attempts to link to itself. This policy was introduced in CMake version 3.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 diff --git a/Help/policy/CMP0039.rst b/Help/policy/CMP0039.rst index 97d78ae2a..4b14e21ae 100644 --- a/Help/policy/CMP0039.rst +++ b/Help/policy/CMP0039.rst @@ -7,13 +7,13 @@ CMake 2.8.12 and lower allowed using utility targets in the left hand side position of the :command:`target_link_libraries` command. This is an indicator of a bug in user code. -The OLD behavior for this policy is to ignore attempts to set the link -libraries of utility targets. The NEW behavior for this policy is to +The ``OLD`` behavior for this policy is to ignore attempts to set the link +libraries of utility targets. The ``NEW`` behavior for this policy is to report an error if an attempt is made to set the link libraries of a utility target. This policy was introduced in CMake version 3.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 diff --git a/Help/policy/CMP0041.rst b/Help/policy/CMP0041.rst index f027d5de9..3b4df3601 100644 --- a/Help/policy/CMP0041.rst +++ b/Help/policy/CMP0041.rst @@ -15,13 +15,13 @@ As an additional diagnostic, the :prop_tgt:`INTERFACE_INCLUDE_DIRECTORIES` gener on an :prop_tgt:`IMPORTED` target for the install location should not contain paths in the source directory or the build directory. -The OLD behavior for this policy is to ignore relative path entries if they -contain a generator expression. The NEW behavior for this policy is to report +The ``OLD`` behavior for this policy is to ignore relative path entries if they +contain a generator expression. The ``NEW`` behavior for this policy is to report an error if a generator expression appears in another location and the path is relative. This policy was introduced in CMake version 3.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 diff --git a/Help/policy/CMP0042.rst b/Help/policy/CMP0042.rst index 31314b2cd..087756450 100644 --- a/Help/policy/CMP0042.rst +++ b/Help/policy/CMP0042.rst @@ -15,7 +15,7 @@ the :prop_tgt:`INSTALL_NAME_DIR` and :variable:`CMAKE_INSTALL_NAME_DIR` variables. This policy was introduced in CMake version 3.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 diff --git a/Help/policy/CMP0043.rst b/Help/policy/CMP0043.rst index 9e427c377..05210ac6e 100644 --- a/Help/policy/CMP0043.rst +++ b/Help/policy/CMP0043.rst @@ -35,13 +35,13 @@ or via :command:`target_compile_definitions`: COMPILE_DEFINITIONS $<$<CONFIG:Debug>:DIR_DEBUG_MODE> ) -The OLD behavior for this policy is to consume the content of the suffixed +The ``OLD`` behavior for this policy is to consume the content of the suffixed :prop_tgt:`COMPILE_DEFINITIONS_<CONFIG>` target property when generating the -compilation command. The NEW behavior for this policy is to ignore the content +compilation command. The ``NEW`` behavior for this policy is to ignore the content of the :prop_tgt:`COMPILE_DEFINITIONS_<CONFIG>` target property . This policy was introduced in CMake version 3.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 diff --git a/Help/policy/CMP0044.rst b/Help/policy/CMP0044.rst index 02afa9f1a..6a4d040b1 100644 --- a/Help/policy/CMP0044.rst +++ b/Help/policy/CMP0044.rst @@ -9,13 +9,13 @@ comparison of the :variable:`CMAKE_<LANG>_COMPILER_ID` with a test value. The possible valid values are lowercase, but the comparison with the test value was performed case-insensitively. -The OLD behavior for this policy is to perform a case-insensitive comparison -with the value in the ``<LANG>_COMPILER_ID`` expression. The NEW behavior +The ``OLD`` behavior for this policy is to perform a case-insensitive comparison +with the value in the ``<LANG>_COMPILER_ID`` expression. The ``NEW`` behavior for this policy is to perform a case-sensitive comparison with the value in the ``<LANG>_COMPILER_ID`` expression. This policy was introduced in CMake version 3.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 diff --git a/Help/policy/CMP0045.rst b/Help/policy/CMP0045.rst index c7e1a90f6..80e217b18 100644 --- a/Help/policy/CMP0045.rst +++ b/Help/policy/CMP0045.rst @@ -7,13 +7,13 @@ In CMake 2.8.12 and lower, the :command:`get_target_property` command accepted a non-existent target argument without issuing any error or warning. The result variable is set to a ``-NOTFOUND`` value. -The OLD behavior for this policy is to issue no warning and set the result -variable to a ``-NOTFOUND`` value. The NEW behavior +The ``OLD`` behavior for this policy is to issue no warning and set the result +variable to a ``-NOTFOUND`` value. The ``NEW`` behavior for this policy is to issue a ``FATAL_ERROR`` if the command is called with a non-existent target. This policy was introduced in CMake version 3.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 diff --git a/Help/policy/CMP0046.rst b/Help/policy/CMP0046.rst index 576d1b1cc..bf785842c 100644 --- a/Help/policy/CMP0046.rst +++ b/Help/policy/CMP0046.rst @@ -6,14 +6,14 @@ Error on non-existent dependency in add_dependencies. CMake 2.8.12 and lower silently ignored non-existent dependencies listed in the :command:`add_dependencies` command. -The OLD behavior for this policy is to silently ignore non-existent -dependencies. The NEW behavior for this policy is to report an error +The ``OLD`` behavior for this policy is to silently ignore non-existent +dependencies. The ``NEW`` behavior for this policy is to report an error if non-existent dependencies are listed in the :command:`add_dependencies` command. This policy was introduced in CMake version 3.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. +``OLD`` behavior. Use the :command:`cmake_policy` command to set it +to ``OLD`` or ``NEW`` explicitly. .. include:: DEPRECATED.txt diff --git a/Help/policy/CMP0047.rst b/Help/policy/CMP0047.rst index 882dd7828..9588edd7a 100644 --- a/Help/policy/CMP0047.rst +++ b/Help/policy/CMP0047.rst @@ -15,14 +15,14 @@ language ``<LANG>`` is enabled by the :command:`project` or :command:`enable_language` command. The policy must be set prior to the invocation of either command. -The OLD behavior for this policy is to use the ``GNU`` compiler id -for the qcc and QCC compiler drivers. The NEW behavior for this policy +The ``OLD`` behavior for this policy is to use the ``GNU`` compiler id +for the qcc and QCC compiler drivers. The ``NEW`` behavior for this policy is to use the ``QCC`` compiler id for those drivers. This policy was introduced in CMake version 3.0. Use the -:command:`cmake_policy` command to set this policy to OLD or NEW explicitly. -Unlike most policies, CMake version |release| does *not* warn -by default when this policy is not set and simply uses OLD behavior. +:command:`cmake_policy` command to set this policy to ``OLD`` or ``NEW`` +explicitly. Unlike most policies, CMake version |release| does *not* warn +by default when this policy is not set and simply uses ``OLD`` behavior. See documentation of the :variable:`CMAKE_POLICY_WARNING_CMP0047 <CMAKE_POLICY_WARNING_CMP<NNNN>>` variable to control the warning. diff --git a/Help/policy/CMP0048.rst b/Help/policy/CMP0048.rst index 0e7e60681..e63ec01a2 100644 --- a/Help/policy/CMP0048.rst +++ b/Help/policy/CMP0048.rst @@ -1,24 +1,24 @@ CMP0048 ------- -The :command:`project` command manages VERSION variables. +The :command:`project` command manages ``VERSION`` variables. CMake version 3.0 introduced the ``VERSION`` option of the :command:`project` command to specify a project version as well as the name. In order to keep :variable:`PROJECT_VERSION` and related variables consistent with variable -:variable:`PROJECT_NAME` it is necessary to set the VERSION variables +:variable:`PROJECT_NAME` it is necessary to set the ``VERSION`` variables to the empty string when no ``VERSION`` is given to :command:`project`. -However, this can change behavior for existing projects that set VERSION +However, this can change behavior for existing projects that set ``VERSION`` variables themselves since :command:`project` may now clear them. This policy controls the behavior for compatibility with such projects. -The OLD behavior for this policy is to leave VERSION variables untouched. -The NEW behavior for this policy is to set VERSION as documented by the +The ``OLD`` behavior for this policy is to leave ``VERSION`` variables untouched. +The ``NEW`` behavior for this policy is to set ``VERSION`` as documented by the :command:`project` command. This policy was introduced in CMake version 3.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. +``OLD`` behavior. Use the :command:`cmake_policy` command to set +it to ``OLD`` or ``NEW`` explicitly. .. include:: DEPRECATED.txt diff --git a/Help/policy/CMP0049.rst b/Help/policy/CMP0049.rst index 291bf5752..49b20be17 100644 --- a/Help/policy/CMP0049.rst +++ b/Help/policy/CMP0049.rst @@ -13,13 +13,13 @@ when evaluating source file names:: This was undocumented behavior. -The OLD behavior for this policy is to expand such variables when processing -the target sources. The NEW behavior for this policy is to issue an error +The ``OLD`` behavior for this policy is to expand such variables when processing +the target sources. The ``NEW`` behavior for this policy is to issue an error if such variables need to be expanded. This policy was introduced in CMake version 3.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. +``OLD`` behavior. Use the :command:`cmake_policy` command to set +it to ``OLD`` or ``NEW`` explicitly. .. include:: DEPRECATED.txt diff --git a/Help/policy/CMP0050.rst b/Help/policy/CMP0050.rst index 39e40b698..27e7b1d50 100644 --- a/Help/policy/CMP0050.rst +++ b/Help/policy/CMP0050.rst @@ -8,13 +8,13 @@ which specified an input to a command. This was undocumented behavior. Modern use of CMake associates custom commands with their output, rather than their input. -The OLD behavior for this policy is to allow the use of -:command:`add_custom_command` SOURCE signatures. The NEW behavior for this +The ``OLD`` behavior for this policy is to allow the use of +:command:`add_custom_command` SOURCE signatures. The ``NEW`` behavior for this policy is to issue an error if such a signature is used. This policy was introduced in CMake version 3.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. +``OLD`` behavior. Use the :command:`cmake_policy` command to set it to ``OLD`` or +``NEW`` explicitly. .. include:: DEPRECATED.txt diff --git a/Help/policy/CMP0052.rst b/Help/policy/CMP0052.rst index 0ea5ace77..ee2e6e8de 100644 --- a/Help/policy/CMP0052.rst +++ b/Help/policy/CMP0052.rst @@ -1,7 +1,8 @@ CMP0052 ------- -Reject source and build dirs in installed INTERFACE_INCLUDE_DIRECTORIES. +Reject source and build dirs in installed +:prop_tgt:`INTERFACE_INCLUDE_DIRECTORIES`. CMake 3.0 and lower allowed subdirectories of the source directory or build directory to be in the :prop_tgt:`INTERFACE_INCLUDE_DIRECTORIES` of @@ -13,9 +14,9 @@ broken if either are removed after installation. See :ref:`Include Directories and Usage Requirements` for more on specifying include directories for targets. -The OLD behavior for this policy is to export the content of the +The ``OLD`` behavior for this policy is to export the content of the :prop_tgt:`INTERFACE_INCLUDE_DIRECTORIES` with the source or binary -directory. The NEW behavior for this +directory. The ``NEW`` behavior for this policy is to issue an error if such a directory is used. This policy was introduced in CMake version 3.1. diff --git a/Help/policy/CMP0055.rst b/Help/policy/CMP0055.rst index b3df758fe..bc5ad086b 100644 --- a/Help/policy/CMP0055.rst +++ b/Help/policy/CMP0055.rst @@ -7,13 +7,13 @@ CMake 3.1 and lower allowed calls to the :command:`break` command outside of a loop context and also ignored any given arguments. This was undefined behavior. -The OLD behavior for this policy is to allow :command:`break` to be placed -outside of loop contexts and ignores any arguments. The NEW behavior for this +The ``OLD`` behavior for this policy is to allow :command:`break` to be placed +outside of loop contexts and ignores any arguments. The ``NEW`` behavior for this policy is to issue an error if a misplaced break or any arguments are found. This policy was introduced in CMake version 3.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. +``OLD`` behavior. Use the :command:`cmake_policy` command to set it to ``OLD`` or +``NEW`` explicitly. .. include:: DEPRECATED.txt diff --git a/Help/policy/CMP0056.rst b/Help/policy/CMP0056.rst index 3ba89d576..834da844f 100644 --- a/Help/policy/CMP0056.rst +++ b/Help/policy/CMP0056.rst @@ -14,9 +14,9 @@ the generated project. CMake 3.2 and above prefer to set it so that linker flags are honored as well as compiler flags. This policy provides compatibility with the pre-3.2 behavior. -The OLD behavior for this policy is to not set the value of the +The ``OLD`` behavior for this policy is to not set the value of the :variable:`CMAKE_EXE_LINKER_FLAGS` variable in the generated test -project. The NEW behavior for this policy is to set the value of +project. The ``NEW`` behavior for this policy is to set the value of the :variable:`CMAKE_EXE_LINKER_FLAGS` variable in the test project to the same as it is in the calling project. @@ -27,7 +27,7 @@ variable in the cache. This policy was introduced in CMake version 3.2. Unlike most policies, CMake version |release| does *not* warn by default when this policy -is not set and simply uses OLD behavior. See documentation of the +is not set and simply uses ``OLD`` behavior. See documentation of the :variable:`CMAKE_POLICY_WARNING_CMP0056 <CMAKE_POLICY_WARNING_CMP<NNNN>>` variable to control the warning. diff --git a/Help/policy/CMP0060.rst b/Help/policy/CMP0060.rst index 8611affac..98ac2cf69 100644 --- a/Help/policy/CMP0060.rst +++ b/Help/policy/CMP0060.rst @@ -51,14 +51,14 @@ and link libraries by full path even when they are in implicit link directories. Policy ``CMP0060`` provides compatibility for existing projects. -The OLD behavior for this policy is to ask the linker to search for +The ``OLD`` behavior for this policy is to ask the linker to search for libraries whose full paths are known to be in implicit link directories. -The NEW behavior for this policy is to link libraries by full path even +The ``NEW`` behavior for this policy is to link libraries by full path even if they are in implicit link directories. This policy was introduced in CMake version 3.3. Unlike most policies, CMake version |release| does *not* warn by default when this policy -is not set and simply uses OLD behavior. See documentation of the +is not set and simply uses ``OLD`` behavior. See documentation of the :variable:`CMAKE_POLICY_WARNING_CMP0060 <CMAKE_POLICY_WARNING_CMP<NNNN>>` variable to control the warning. diff --git a/Help/policy/CMP0061.rst b/Help/policy/CMP0061.rst index cb2ac2840..57e4161d0 100644 --- a/Help/policy/CMP0061.rst +++ b/Help/policy/CMP0061.rst @@ -21,6 +21,6 @@ add ``-i``. This policy was introduced in CMake version 3.3. Unlike most policies, CMake version |release| does *not* warn when this policy is not set and -simply uses OLD behavior. +simply uses ``OLD`` behavior. .. include:: DEPRECATED.txt diff --git a/Help/policy/CMP0062.rst b/Help/policy/CMP0062.rst index 9047fffbe..0db7aafd0 100644 --- a/Help/policy/CMP0062.rst +++ b/Help/policy/CMP0062.rst @@ -1,7 +1,7 @@ CMP0062 ------- -Disallow install() of export() result. +Disallow :command:`install` of :command:`export` result. The :command:`export()` command generates a file containing :ref:`Imported Targets`, which is suitable for use from the build diff --git a/Help/policy/CMP0065.rst b/Help/policy/CMP0065.rst index 2ed775dee..b820aad51 100644 --- a/Help/policy/CMP0065.rst +++ b/Help/policy/CMP0065.rst @@ -20,7 +20,7 @@ property is set to ``True``. This policy was introduced in CMake version 3.4. Unlike most policies, CMake version |release| does *not* warn by default when this policy -is not set and simply uses OLD behavior. See documentation of the +is not set and simply uses ``OLD`` behavior. See documentation of the :variable:`CMAKE_POLICY_WARNING_CMP0065 <CMAKE_POLICY_WARNING_CMP<NNNN>>` variable to control the warning. diff --git a/Help/policy/CMP0066.rst b/Help/policy/CMP0066.rst index d1dcb0ec6..e110ae127 100644 --- a/Help/policy/CMP0066.rst +++ b/Help/policy/CMP0066.rst @@ -20,7 +20,7 @@ variabldes like :variable:`CMAKE_<LANG>_FLAGS_DEBUG`. This policy was introduced in CMake version 3.7. Unlike most policies, CMake version |release| does *not* warn by default when this policy -is not set and simply uses OLD behavior. See documentation of the +is not set and simply uses ``OLD`` behavior. See documentation of the :variable:`CMAKE_POLICY_WARNING_CMP0066 <CMAKE_POLICY_WARNING_CMP<NNNN>>` variable to control the warning. diff --git a/Help/policy/CMP0067.rst b/Help/policy/CMP0067.rst index e6dda8018..f802787ff 100644 --- a/Help/policy/CMP0067.rst +++ b/Help/policy/CMP0067.rst @@ -30,7 +30,7 @@ setting variables. This policy was introduced in CMake version 3.8. Unlike most policies, CMake version |release| does *not* warn by default when this policy -is not set and simply uses OLD behavior. See documentation of the +is not set and simply uses ``OLD`` behavior. See documentation of the :variable:`CMAKE_POLICY_WARNING_CMP0067 <CMAKE_POLICY_WARNING_CMP<NNNN>>` variable to control the warning. diff --git a/Help/policy/CMP0071.rst b/Help/policy/CMP0071.rst index ee33aa1c2..855ecf0e9 100644 --- a/Help/policy/CMP0071.rst +++ b/Help/policy/CMP0071.rst @@ -21,7 +21,7 @@ source files. .. note:: - To silence the CMP0071 warning source files can be excluded from + To silence the ``CMP0071`` warning source files can be excluded from :prop_tgt:`AUTOMOC` and :prop_tgt:`AUTOUIC` processing by setting the source file properties :prop_sf:`SKIP_AUTOMOC`, :prop_sf:`SKIP_AUTOUIC` or :prop_sf:`SKIP_AUTOGEN`. diff --git a/Help/policy/CMP0082.rst b/Help/policy/CMP0082.rst index 8256444c8..d887616be 100644 --- a/Help/policy/CMP0082.rst +++ b/Help/policy/CMP0082.rst @@ -19,7 +19,7 @@ declared. This policy was introduced in CMake version 3.14. Unlike most policies, CMake version |release| does *not* warn by default when this policy -is not set and simply uses OLD behavior. See documentation of the +is not set and simply uses ``OLD`` behavior. See documentation of the :variable:`CMAKE_POLICY_WARNING_CMP0082 <CMAKE_POLICY_WARNING_CMP<NNNN>>` variable to control the warning. diff --git a/Help/policy/CMP0089.rst b/Help/policy/CMP0089.rst new file mode 100644 index 000000000..029de5534 --- /dev/null +++ b/Help/policy/CMP0089.rst @@ -0,0 +1,30 @@ +CMP0089 +------- + +Compiler id for IBM Clang-based XL compilers is now ``XLClang``. + +CMake 3.15 and above recognize that IBM's Clang-based XL compilers +that define ``__ibmxl__`` are a new front-end distinct from ``xlc`` +with a different command line and set of capabilities. +CMake now prefers to present this to projects by setting the +:variable:`CMAKE_<LANG>_COMPILER_ID` variable to ``XLClang`` instead +of ``XL``. However, existing projects may assume the compiler id for +Clang-based XL is just ``XL`` as it was in CMake versions prior to 3.15. +Therefore this policy determines for Clang-based XL compilers which +compiler id to report in the :variable:`CMAKE_<LANG>_COMPILER_ID` +variable after language ``<LANG>`` is enabled by the :command:`project` +or :command:`enable_language` command. The policy must be set prior +to the invocation of either command. + +The ``OLD`` behavior for this policy is to use compiler id ``XL``. The +``NEW`` behavior for this policy is to use compiler id ``XLClang``. + +This policy was introduced in CMake version 3.15. Use the +:command:`cmake_policy` command to set this policy to ``OLD`` or ``NEW`` explicitly. +Unlike most policies, CMake version |release| does *not* warn +by default when this policy is not set and simply uses ``OLD`` behavior. +See documentation of the +:variable:`CMAKE_POLICY_WARNING_CMP0089 <CMAKE_POLICY_WARNING_CMP<NNNN>>` +variable to control the warning. + +.. include:: DEPRECATED.txt diff --git a/Help/policy/CMP0090.rst b/Help/policy/CMP0090.rst new file mode 100644 index 000000000..720c17c2a --- /dev/null +++ b/Help/policy/CMP0090.rst @@ -0,0 +1,27 @@ +CMP0090 +------- + +:command:`export(PACKAGE)` does not populate package registry by default. + +In CMake 3.14 and below the :command:`export(PACKAGE)` command populated the +user package registry by default and users needed to set the +:variable:`CMAKE_EXPORT_NO_PACKAGE_REGISTRY` to disable it, e.g. in automated +build and packaging environments. Since the user package registry is stored +outside the build tree, this side effect should not be enabled by default. +Therefore CMake 3.15 and above prefer that :command:`export(PACKAGE)` does +nothing unless an explicit :variable:`CMAKE_EXPORT_PACKAGE_REGISTRY` variable +is set to enable it. This policy provides compatibility with projects that +have not been updated. + +The ``OLD`` behavior for this policy is for :command:`export(PACKAGE)` command +to populate the user package registry unless +:variable:`CMAKE_EXPORT_NO_PACKAGE_REGISTRY` is enabled. +The ``NEW`` behavior is for :command:`export(PACKAGE)` command to do nothing +unless the :variable:`CMAKE_EXPORT_PACKAGE_REGISTRY` is enabled. + +This policy was introduced in CMake version 3.15. Use the +:command:`cmake_policy` command to set it to ``OLD`` or ``NEW`` explicitly. +Unlike most policies, CMake version |release| does *not* warn +when this policy is not set and simply uses ``OLD`` behavior. + +.. include:: DEPRECATED.txt diff --git a/Help/policy/CMP0091.rst b/Help/policy/CMP0091.rst new file mode 100644 index 000000000..5b7c4e3d9 --- /dev/null +++ b/Help/policy/CMP0091.rst @@ -0,0 +1,47 @@ +CMP0091 +------- + +MSVC runtime library flags are selected by an abstraction. + +Compilers targeting the MSVC ABI have flags to select the MSVC runtime library. +Runtime library selection typically varies with build configuration because +there is a separate runtime library for Debug builds. + +In CMake 3.14 and below, MSVC runtime library selection flags are added to +the default :variable:`CMAKE_<LANG>_FLAGS_<CONFIG>` cache entries by CMake +automatically. This allows users to edit their cache entries to adjust the +flags. However, the presence of such default flags is problematic for +projects that want to choose a different runtime library programmatically. +In particular, it requires string editing of the +:variable:`CMAKE_<LANG>_FLAGS_<CONFIG>` variables with knowledge of the +CMake builtin defaults so they can be replaced. + +CMake 3.15 and above prefer to leave the MSVC runtime library selection flags +out of the default :variable:`CMAKE_<LANG>_FLAGS_<CONFIG>` values and instead +offer a first-class abstraction. The :variable:`CMAKE_MSVC_RUNTIME_LIBRARY` +variable and :prop_tgt:`MSVC_RUNTIME_LIBRARY` target property may be set to +select the MSVC runtime library. + +This policy provides compatibility with projects that have not been updated +to be aware of the abstraction. The policy setting takes effect as of the +first :command:`project` or :command:`enable_language` command that enables +a language whose compiler targets the MSVC ABI. + +.. note:: + + Once the policy has taken effect at the top of a project, that choice + must be used throughout the tree. In projects that have nested projects + in subdirectories, be sure to convert everything together. + +The ``OLD`` behavior for this policy is to place MSVC runtime library +flags in the default :variable:`CMAKE_<LANG>_FLAGS_<CONFIG>` cache +entries and ignore the :variable:`CMAKE_MSVC_RUNTIME_LIBRARY` abstraction. +The ``NEW`` behavior for this policy is to *not* place MSVC runtime +library flags in the default cache entries and use the abstraction instead. + +This policy was introduced in CMake version 3.15. Use the +:command:`cmake_policy` command to set it to ``OLD`` or ``NEW`` explicitly. +Unlike many policies, CMake version |release| does *not* warn +when this policy is not set and simply uses ``OLD`` behavior. + +.. include:: DEPRECATED.txt diff --git a/Help/policy/CMP0092.rst b/Help/policy/CMP0092.rst new file mode 100644 index 000000000..8d3a288ae --- /dev/null +++ b/Help/policy/CMP0092.rst @@ -0,0 +1,38 @@ +CMP0092 +------- + +MSVC warning flags are not in :variable:`CMAKE_<LANG>_FLAGS` by default. + +When using MSVC-like compilers in CMake 3.14 and below, warning flags +like ``/W3`` are added to :variable:`CMAKE_<LANG>_FLAGS` by default. +This is problematic for projects that want to choose a different warning +level programmatically. In particular, it requires string editing of the +:variable:`CMAKE_<LANG>_FLAGS` variables with knowledge of the +CMake builtin defaults so they can be replaced. + +CMake 3.15 and above prefer to leave out warning flags from the value of +:variable:`CMAKE_<LANG>_FLAGS` by default. + +This policy provides compatibility with projects that have not been updated +to expect the lack of warning flags. The policy setting takes effect as of +the first :command:`project` or :command:`enable_language` command that +initializes :variable:`CMAKE_<LANG>_FLAGS` for a given lanuage ``<LANG>``. + +.. note:: + + Once the policy has taken effect at the top of a project for a given + language, that choice must be used throughout the tree for that language. + In projects that have nested projects in subdirectories, be sure to + convert everything together. + +The ``OLD`` behavior for this policy is to place MSVC warning flags in the +default :variable:`CMAKE_<LANG>_FLAGS` cache entries. The ``NEW`` behavior +for this policy is to *not* place MSVC warning flags in the default cache +entries. + +This policy was introduced in CMake version 3.15. Use the +:command:`cmake_policy` command to set it to ``OLD`` or ``NEW`` explicitly. +Unlike many policies, CMake version |release| does *not* warn +when this policy is not set and simply uses ``OLD`` behavior. + +.. include:: DEPRECATED.txt diff --git a/Help/policy/CMP0093.rst b/Help/policy/CMP0093.rst new file mode 100644 index 000000000..0ffc493de --- /dev/null +++ b/Help/policy/CMP0093.rst @@ -0,0 +1,24 @@ +CMP0093 +------- + +:module:`FindBoost` reports ``Boost_VERSION`` in ``x.y.z`` format. + +In CMake 3.14 and below the module would report the Boost version +number as specified in the preprocessor definition ``BOOST_VERSION`` in +the ``boost/version.hpp`` file. In CMake 3.15 and later it is preferred +that the reported version number matches the ``x.y.z`` format reported +by the CMake package shipped with Boost ``1.70.0`` and later. The macro +value is still reported in the ``Boost_VERSION_MACRO`` variable. + +The ``OLD`` behavior for this policy is for :module:`FindBoost` to report +``Boost_VERSION`` as specified in the preprocessor definition +``BOOST_VERSION`` in ``boost/version.hpp``. The ``NEW`` behavior for this +policy is for :module:`FindBoost` to report ``Boost_VERSION`` in +``x.y.z`` format. + +This policy was introduced in CMake version 3.15. Use the +:command:`cmake_policy` command to set it to ``OLD`` or ``NEW`` explicitly. +Unlike many policies, CMake version |release| does *not* warn +when this policy is not set and simply uses the ``OLD`` behavior. + +.. include:: DEPRECATED.txt diff --git a/Help/policy/CMP0094.rst b/Help/policy/CMP0094.rst new file mode 100644 index 000000000..836f30f09 --- /dev/null +++ b/Help/policy/CMP0094.rst @@ -0,0 +1,22 @@ +CMP0094 +------- + +Modules :module:`FindPython3`, :module:`FindPython2` and :module:`FindPython` +use ``LOCATION`` for lookup strategy. + +Starting with CMake 3.15, Modules :module:`FindPython3`, :module:`FindPython2` +and :module:`FindPython` set value ``LOCATION`` for, respectively, variables +``Python3_FIND_STRATEGY``, ``Python2_FIND_STRATEGY`` and +``Python_FIND_STRATEGY``. This policy provides compatibility with projects that +expect the legacy behavior. + +The ``OLD`` behavior for this policy set value ``VERSION`` for variables +``Python3_FIND_STRATEGY``, ``Python2_FIND_STRATEGY`` and +``Python_FIND_STRATEGY``. + +This policy was introduced in CMake version 3.15. Use the +:command:`cmake_policy` command to set it to ``OLD`` or ``NEW`` explicitly. +Unlike many policies, CMake version |release| does *not* warn +when this policy is not set and simply uses the ``OLD`` behavior. + +.. include:: DEPRECATED.txt diff --git a/Help/policy/DISALLOWED_COMMAND.txt b/Help/policy/DISALLOWED_COMMAND.txt index 36280d2b6..6500bb0f3 100644 --- a/Help/policy/DISALLOWED_COMMAND.txt +++ b/Help/policy/DISALLOWED_COMMAND.txt @@ -1,9 +1,9 @@ CMake >= |disallowed_version| prefer that this command never be called. -The OLD behavior for this policy is to allow the command to be called. -The NEW behavior for this policy is to issue a FATAL_ERROR when the +The ``OLD`` behavior for this policy is to allow the command to be called. +The ``NEW`` behavior for this policy is to issue a ``FATAL_ERROR`` when the command is called. This policy was introduced in CMake version |disallowed_version|. 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. +``OLD`` behavior. Use the :command:`cmake_policy` command to set it to ``OLD`` or +``NEW`` explicitly. |