diff options
Diffstat (limited to 'Help')
| -rw-r--r-- | Help/command/if.rst | 11 | ||||
| -rw-r--r-- | Help/command/list.rst | 15 | ||||
| -rw-r--r-- | Help/manual/cmake-properties.7.rst | 1 | ||||
| -rw-r--r-- | Help/manual/cmake-variables.7.rst | 1 | ||||
| -rw-r--r-- | Help/manual/cmake.1.rst | 14 | ||||
| -rw-r--r-- | Help/policy/CMP0028.rst | 2 | ||||
| -rw-r--r-- | Help/policy/CMP0126.rst | 3 | ||||
| -rw-r--r-- | Help/prop_tgt/LINK_LIBRARIES_ONLY_TARGETS.rst | 55 | ||||
| -rw-r--r-- | Help/release/dev/FindGLUT-include-dirs.rst | 7 | ||||
| -rw-r--r-- | Help/release/dev/filter-debug-find.rst | 10 | ||||
| -rw-r--r-- | Help/release/dev/link-only-targets.rst | 7 | ||||
| -rw-r--r-- | Help/variable/CMAKE_LINK_LIBRARIES_ONLY_TARGETS.rst | 10 |
12 files changed, 132 insertions, 4 deletions
diff --git a/Help/command/if.rst b/Help/command/if.rst index 5dba13e..6957142 100644 --- a/Help/command/if.rst +++ b/Help/command/if.rst @@ -126,7 +126,16 @@ Existence Checks ``if(DEFINED <name>|CACHE{<name>}|ENV{<name>})`` True if a variable, cache variable or environment variable with given ``<name>`` is defined. The value of the variable - does not matter. Note that macro arguments are not variables. + does not matter. Note the following caveats: + + * Macro arguments are not variables. + * It is not possible to test directly whether a `<name>` is a non-cache + variable. The expression ``if(DEFINED someName)`` will evaluate to true + if either a cache or non-cache variable ``someName`` exists. In + comparison, the expression ``if(DEFINED CACHE{someName})`` will only + evaluate to true if a cache variable ``someName`` exists. Both expressions + need to be tested if you need to know whether a non-cache variable exists: + ``if(DEFINED someName AND NOT DEFINED CACHE{someName})``. .. versionadded:: 3.14 Added support for ``CACHE{<name>}`` variables. diff --git a/Help/command/list.rst b/Help/command/list.rst index 9b49cb4..33c4f80 100644 --- a/Help/command/list.rst +++ b/Help/command/list.rst @@ -128,7 +128,9 @@ Modification list(APPEND <list> [<element> ...]) -Appends elements to the list. +Appends elements to the list. If no variable named ``<list>`` exists in the +current scope its value is treated as empty and the elements are appended to +that empty list. .. _FILTER: @@ -150,7 +152,12 @@ For more information on regular expressions look under list(INSERT <list> <element_index> <element> [<element> ...]) -Inserts elements to the list to the specified location. +Inserts elements to the list to the specified index. It is an +error to specify an out-of-range index. Valid indexes are 0 to `N` +where `N` is the length of the list, inclusive. An empty list +has length 0. If no variable named ``<list>`` exists in the +current scope its value is treated as empty and the elements are +inserted in that empty list. .. _POP_BACK: @@ -186,7 +193,9 @@ to the given variables and then remove the first `N` values from .. versionadded:: 3.15 -Insert elements to the 0th position in the list. +Insert elements to the 0th position in the list. If no variable named +``<list>`` exists in the current scope its value is treated as empty and +the elements are prepended to that empty list. .. _REMOVE_ITEM: diff --git a/Help/manual/cmake-properties.7.rst b/Help/manual/cmake-properties.7.rst index 73e57d1..ddb917a 100644 --- a/Help/manual/cmake-properties.7.rst +++ b/Help/manual/cmake-properties.7.rst @@ -305,6 +305,7 @@ Properties on Targets /prop_tgt/LINK_INTERFACE_MULTIPLICITY /prop_tgt/LINK_INTERFACE_MULTIPLICITY_CONFIG /prop_tgt/LINK_LIBRARIES + /prop_tgt/LINK_LIBRARIES_ONLY_TARGETS /prop_tgt/LINK_OPTIONS /prop_tgt/LINK_SEARCH_END_STATIC /prop_tgt/LINK_SEARCH_START_STATIC diff --git a/Help/manual/cmake-variables.7.rst b/Help/manual/cmake-variables.7.rst index 13704c5..51b092f 100644 --- a/Help/manual/cmake-variables.7.rst +++ b/Help/manual/cmake-variables.7.rst @@ -221,6 +221,7 @@ Variables that Change Behavior /variable/CMAKE_INSTALL_PREFIX_INITIALIZED_TO_DEFAULT /variable/CMAKE_LIBRARY_PATH /variable/CMAKE_LINK_DIRECTORIES_BEFORE + /variable/CMAKE_LINK_LIBRARIES_ONLY_TARGETS /variable/CMAKE_MFC_FLAG /variable/CMAKE_MAXIMUM_RECURSION_DEPTH /variable/CMAKE_MESSAGE_CONTEXT diff --git a/Help/manual/cmake.1.rst b/Help/manual/cmake.1.rst index e23ddd8..04e2eda 100644 --- a/Help/manual/cmake.1.rst +++ b/Help/manual/cmake.1.rst @@ -250,6 +250,20 @@ Options See also the :variable:`CMAKE_FIND_DEBUG_MODE` variable for debugging a more local part of the project. +``--debug-find=<pkg>[,...]`` + Put cmake find commands in a debug mode when running under calls + to ``find_package(<pkg>)``, where ``<pkg>`` is an entry in the given + comma-separated list of case-sensitive package names. + + Like ``--debug-find``, but limiting scope to the specified packages. + +``--debug-find-var=<var>[,...]`` + Put cmake find commands in a debug mode when called with ``<var>`` + as the return variable, where ``<var>`` is an entry in the given + comma-separated list. + + Like ``--debug-find``, but limiting scope to the specified variable names. + ``--trace`` Put cmake in trace mode. diff --git a/Help/policy/CMP0028.rst b/Help/policy/CMP0028.rst index ab38229..dcd39d8 100644 --- a/Help/policy/CMP0028.rst +++ b/Help/policy/CMP0028.rst @@ -13,6 +13,8 @@ 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. +See also the :prop_tgt:`LINK_LIBRARIES_ONLY_TARGETS` target property. + 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 diff --git a/Help/policy/CMP0126.rst b/Help/policy/CMP0126.rst index 1b69957..a389512 100644 --- a/Help/policy/CMP0126.rst +++ b/Help/policy/CMP0126.rst @@ -14,6 +14,9 @@ current scope in the following situations: This can occur when the variable was set on the command line using a form like ``cmake -DMYVAR=blah`` instead of ``cmake -DMYVAR:STRING=blah``. +* The ``FORCE`` or ``INTERNAL`` keywords were used when setting the cache + variable. + Note that the ``NEW`` behavior has an important difference to the similar ``NEW`` behavior of policy :policy:`CMP0077`. The :command:`set(CACHE)` command always sets the cache variable if it did not exist previously, diff --git a/Help/prop_tgt/LINK_LIBRARIES_ONLY_TARGETS.rst b/Help/prop_tgt/LINK_LIBRARIES_ONLY_TARGETS.rst new file mode 100644 index 0000000..78fbb02 --- /dev/null +++ b/Help/prop_tgt/LINK_LIBRARIES_ONLY_TARGETS.rst @@ -0,0 +1,55 @@ +LINK_LIBRARIES_ONLY_TARGETS +--------------------------- + +.. versionadded:: 3.23 + +Enforce that link items that can be target names are actually existing targets. + +Set this property to a true value to enable additional checks on the contents +of the :prop_tgt:`LINK_LIBRARIES` and :prop_tgt:`INTERFACE_LINK_LIBRARIES` +target properties, typically populated by :command:`target_link_libraries`. +CMake will verify that link items that might be target names actually name +existing targets. An item is considered a possible target name if: + +* it does not contain a ``/`` or ``\``, and +* it does not start in ``-``, and +* (for historical reasons) it does not start in ``$`` or `````. + +This property is initialized by the value of the +:variable:`CMAKE_LINK_LIBRARIES_ONLY_TARGETS` variable when a non-imported +target is created. The property may be explicitly enabled on an imported +target to check its link interface. + +For example, the following code: + +.. code-block:: cmake + + set(CMAKE_LINK_LIBRARIES_ONLY_TARGETS ON) + add_executable(myLib STATIC myLib.c) + add_executable(myExe myExe.c) + target_link_libraries(myExe PRIVATE miLib) # typo for myLib + +will produce a CMake-time error that ``miLib`` is not a target. + +In order to link toolchain-provided libraries by name while still +enforcing ``LINK_LIBRARIES_ONLY_TARGETS``, use an +:ref:`imported <Imported Targets>` +:ref:`Interface Library <Interface Libraries>` with the +:prop_tgt:`IMPORTED_LIBNAME` target property: + +.. code-block:: cmake + + add_library(toolchain::m INTERFACE IMPORTED) + set_property(TARGET toolchain::m PROPERTY IMPORTED_LIBNAME "m") + target_link_libraries(myExe PRIVATE toolchain::m) + +See also policy :policy:`CMP0028`. + +.. note:: + + If :prop_tgt:`INTERFACE_LINK_LIBRARIES` contains generator expressions, + its actual list of link items may depend on the type and properties of + the consuming target. In such cases CMake may not always detect names + of missing targets that only appear for specific consumers. + A future version of CMake with improved heuristics may start triggering + errors on projects accepted by previous versions of CMake. diff --git a/Help/release/dev/FindGLUT-include-dirs.rst b/Help/release/dev/FindGLUT-include-dirs.rst new file mode 100644 index 0000000..9528892 --- /dev/null +++ b/Help/release/dev/FindGLUT-include-dirs.rst @@ -0,0 +1,7 @@ +FindGLUT-include-dirs +--------------------- + +* The :module:`FindGLUT` module now provides the ``GLUT_INCLUDE_DIRS`` + result variable to conform with naming conventions documented in the + :manual:`cmake-developer(7)` manual. This supersedes the legacy + ``GLUT_INCLUDE_DIR`` variable. diff --git a/Help/release/dev/filter-debug-find.rst b/Help/release/dev/filter-debug-find.rst new file mode 100644 index 0000000..8bdb61e --- /dev/null +++ b/Help/release/dev/filter-debug-find.rst @@ -0,0 +1,10 @@ +filter-debug-find +----------------- + +* The :manual:`cmake(1)` command line tool's gained a + ``--debug-find-pkg=`` option to enable debug messages under specific + :command:`find_package` calls. + +* The :manual:`cmake(1)` command line tool gained a ``--debug-find-var=`` + option to enable debug messages for ``find_*`` calls that use specific + result variables. diff --git a/Help/release/dev/link-only-targets.rst b/Help/release/dev/link-only-targets.rst new file mode 100644 index 0000000..7901a25 --- /dev/null +++ b/Help/release/dev/link-only-targets.rst @@ -0,0 +1,7 @@ +link-only-targets +----------------- + +* The :variable:`CMAKE_LINK_LIBRARIES_ONLY_TARGETS` variable and + corresponding :prop_tgt:`LINK_LIBRARIES_ONLY_TARGETS` target + property were added to optionally require that all link items + that can be target names are actually names of existing targets. diff --git a/Help/variable/CMAKE_LINK_LIBRARIES_ONLY_TARGETS.rst b/Help/variable/CMAKE_LINK_LIBRARIES_ONLY_TARGETS.rst new file mode 100644 index 0000000..513c3d0 --- /dev/null +++ b/Help/variable/CMAKE_LINK_LIBRARIES_ONLY_TARGETS.rst @@ -0,0 +1,10 @@ +CMAKE_LINK_LIBRARIES_ONLY_TARGETS +--------------------------------- + +.. versionadded:: 3.23 + +Set this variable to initialize the :prop_tgt:`LINK_LIBRARIES_ONLY_TARGETS` +property of non-imported targets when they are created. Setting it to true +enables an additional check that all items named by +:command:`target_link_libraries` that can be target names are actually names +of existing targets. See the target property documentation for details. |