Merge topic 'help.file'
d2d2ffe1c1 Help: file: document GET_RUNTIME_DEPENDENCIES separately
Acked-by: Kitware Robot <kwrobot@kitware.com>
Acked-by: buildbot <buildbot@kitware.com>
Acked-by: Juan Ramos <juan.ramos@kitware.com>
Merge-request: !9456
diff --git a/Help/command/target_compile_definitions.rst b/Help/command/target_compile_definitions.rst
index 2290efb..5796b00 100644
--- a/Help/command/target_compile_definitions.rst
+++ b/Help/command/target_compile_definitions.rst
@@ -15,7 +15,7 @@
:ref:`ALIAS target <Alias Targets>`.
The ``INTERFACE``, ``PUBLIC`` and ``PRIVATE`` keywords are required to
-specify the :ref:`scope <Target Usage Requirements>` of the following arguments.
+specify the :ref:`scope <Target Command Scope>` of the following arguments.
``PRIVATE`` and ``PUBLIC`` items will populate the :prop_tgt:`COMPILE_DEFINITIONS`
property of ``<target>``. ``PUBLIC`` and ``INTERFACE`` items will populate the
:prop_tgt:`INTERFACE_COMPILE_DEFINITIONS` property of ``<target>``.
diff --git a/Help/command/target_compile_options.rst b/Help/command/target_compile_options.rst
index 7cfb24b..64f45aa 100644
--- a/Help/command/target_compile_options.rst
+++ b/Help/command/target_compile_options.rst
@@ -28,7 +28,7 @@
whether ``BEFORE`` will be ignored in certain cases.
The ``INTERFACE``, ``PUBLIC`` and ``PRIVATE`` keywords are required to
-specify the :ref:`scope <Target Usage Requirements>` of the following arguments.
+specify the :ref:`scope <Target Command Scope>` of the following arguments.
``PRIVATE`` and ``PUBLIC`` items will populate the :prop_tgt:`COMPILE_OPTIONS`
property of ``<target>``. ``PUBLIC`` and ``INTERFACE`` items will populate the
:prop_tgt:`INTERFACE_COMPILE_OPTIONS` property of ``<target>``.
diff --git a/Help/command/target_include_directories.rst b/Help/command/target_include_directories.rst
index 2a410ec..bb5f9c3 100644
--- a/Help/command/target_include_directories.rst
+++ b/Help/command/target_include_directories.rst
@@ -18,7 +18,7 @@
and prepending, independent of the default.
The ``INTERFACE``, ``PUBLIC`` and ``PRIVATE`` keywords are required to specify
-the :ref:`scope <Target Usage Requirements>` of the following arguments.
+the :ref:`scope <Target Command Scope>` of the following arguments.
``PRIVATE`` and ``PUBLIC`` items will populate the :prop_tgt:`INCLUDE_DIRECTORIES`
property of ``<target>``. ``PUBLIC`` and ``INTERFACE`` items will populate the
:prop_tgt:`INTERFACE_INCLUDE_DIRECTORIES` property of ``<target>``.
diff --git a/Help/command/target_link_directories.rst b/Help/command/target_link_directories.rst
index 2854c96..67d3352 100644
--- a/Help/command/target_link_directories.rst
+++ b/Help/command/target_link_directories.rst
@@ -21,7 +21,7 @@
:ref:`ALIAS target <Alias Targets>`.
The ``INTERFACE``, ``PUBLIC`` and ``PRIVATE`` keywords are required to
-specify the :ref:`scope <Target Usage Requirements>` of the items that follow
+specify the :ref:`scope <Target Command Scope>` of the items that follow
them. ``PRIVATE`` and ``PUBLIC`` items will populate the
:prop_tgt:`LINK_DIRECTORIES` property of ``<target>``. ``PUBLIC`` and
``INTERFACE`` items will populate the :prop_tgt:`INTERFACE_LINK_DIRECTORIES`
diff --git a/Help/command/target_link_libraries.rst b/Help/command/target_link_libraries.rst
index 68d3598..a82adda 100644
--- a/Help/command/target_link_libraries.rst
+++ b/Help/command/target_link_libraries.rst
@@ -153,7 +153,7 @@
[<PRIVATE|PUBLIC|INTERFACE> <item>...]...)
The ``PUBLIC``, ``PRIVATE`` and ``INTERFACE``
-:ref:`scope <Target Usage Requirements>` keywords can be used to
+:ref:`scope <Target Command Scope>` keywords can be used to
specify both the link dependencies and the link interface in one command.
Libraries and targets following ``PUBLIC`` are linked to, and are made
diff --git a/Help/command/target_link_options.rst b/Help/command/target_link_options.rst
index dca9598..7561c99 100644
--- a/Help/command/target_link_options.rst
+++ b/Help/command/target_link_options.rst
@@ -32,7 +32,7 @@
instead of being appended.
The ``INTERFACE``, ``PUBLIC`` and ``PRIVATE`` keywords are required to
-specify the :ref:`scope <Target Usage Requirements>` of the following arguments.
+specify the :ref:`scope <Target Command Scope>` of the following arguments.
``PRIVATE`` and ``PUBLIC`` items will populate the :prop_tgt:`LINK_OPTIONS`
property of ``<target>``. ``PUBLIC`` and ``INTERFACE`` items will populate the
:prop_tgt:`INTERFACE_LINK_OPTIONS` property of ``<target>``.
diff --git a/Help/command/target_precompile_headers.rst b/Help/command/target_precompile_headers.rst
index 50eaf22..61ea0aa 100644
--- a/Help/command/target_precompile_headers.rst
+++ b/Help/command/target_precompile_headers.rst
@@ -25,7 +25,7 @@
:ref:`ALIAS target <Alias Targets>`.
The ``INTERFACE``, ``PUBLIC`` and ``PRIVATE`` keywords are required to
-specify the :ref:`scope <Target Usage Requirements>` of the following arguments.
+specify the :ref:`scope <Target Command Scope>` of the following arguments.
``PRIVATE`` and ``PUBLIC`` items will populate the :prop_tgt:`PRECOMPILE_HEADERS`
property of ``<target>``. ``PUBLIC`` and ``INTERFACE`` items will populate the
:prop_tgt:`INTERFACE_PRECOMPILE_HEADERS` property of ``<target>``
diff --git a/Help/command/target_sources.rst b/Help/command/target_sources.rst
index 40755c5..0d31f8c 100644
--- a/Help/command/target_sources.rst
+++ b/Help/command/target_sources.rst
@@ -22,7 +22,7 @@
``<target>`` can be a custom target.
The ``INTERFACE``, ``PUBLIC`` and ``PRIVATE`` keywords are required to
-specify the :ref:`scope <Target Usage Requirements>` of the source file paths
+specify the :ref:`scope <Target Command Scope>` of the source file paths
(``<items>``) that follow them. ``PRIVATE`` and ``PUBLIC`` items will
populate the :prop_tgt:`SOURCES` property of ``<target>``, which are used when
building the target itself. ``PUBLIC`` and ``INTERFACE`` items will populate the
diff --git a/Help/manual/cmake-buildsystem.7.rst b/Help/manual/cmake-buildsystem.7.rst
index b88b864..9eca05d 100644
--- a/Help/manual/cmake-buildsystem.7.rst
+++ b/Help/manual/cmake-buildsystem.7.rst
@@ -162,103 +162,279 @@
Build Specification and Usage Requirements
==========================================
-The :command:`target_include_directories`, :command:`target_compile_definitions`
-and :command:`target_compile_options` commands specify the build specifications
-and the usage requirements of binary targets. The commands populate the
-:prop_tgt:`INCLUDE_DIRECTORIES`, :prop_tgt:`COMPILE_DEFINITIONS` and
-:prop_tgt:`COMPILE_OPTIONS` target properties respectively, and/or the
-:prop_tgt:`INTERFACE_INCLUDE_DIRECTORIES`, :prop_tgt:`INTERFACE_COMPILE_DEFINITIONS`
-and :prop_tgt:`INTERFACE_COMPILE_OPTIONS` target properties.
+Targets build according to their own
+`build specification <Target Build Specification_>`_ in combination with
+`usage requirements <Target Usage Requirements_>`_ propagated from their
+link dependencies. Both may be specified using target-specific
+`commands <Target Commands_>`_.
-Each of the commands has a ``PRIVATE``, ``PUBLIC`` and ``INTERFACE`` mode. The
-``PRIVATE`` mode populates only the non-``INTERFACE_`` variant of the target
-property and the ``INTERFACE`` mode populates only the ``INTERFACE_`` variants.
-The ``PUBLIC`` mode populates both variants of the respective target property.
-Each command may be invoked with multiple uses of each keyword:
+For example:
.. code-block:: cmake
- target_compile_definitions(archive
- PRIVATE BUILDING_WITH_LZMA
- INTERFACE USING_ARCHIVE_LIB
- )
+ add_library(archive SHARED archive.cpp zip.cpp)
+
+ if (LZMA_FOUND)
+ # Add a source implementing support for lzma.
+ target_sources(archive PRIVATE lzma.cpp)
+
+ # Compile the 'archive' library sources with '-DBUILDING_WITH_LZMA'.
+ target_compile_definitions(archive PRIVATE BUILDING_WITH_LZMA)
+ endif()
+
+ target_compile_definitions(archive INTERFACE USING_ARCHIVE_LIB)
+
+ add_executable(consumer consumer.cpp)
+
+ # Link 'consumer' to 'archive'. This also consumes its usage requirements,
+ # so 'consumer.cpp' is compiled with '-DUSING_ARCHIVE_LIB'.
+ target_link_libraries(consumer archive)
+
+
+Target Commands
+---------------
+
+Target-specific commands populate the
+`build specification <Target Build Specification_>`_ of `Binary Targets`_ and
+`usage requirements <Target Usage Requirements_>`_ of `Binary Targets`_,
+`Interface Libraries`_, and `Imported Targets`_.
+
+.. _`Target Command Scope`:
+
+Invocations must specify scope keywords, each affecting the visibility
+of arguments following it. The scopes are:
+
+``PUBLIC``
+ Populates both properties for `building <Target Build Specification_>`_
+ and properties for `using <Target Usage Requirements_>`_ a target.
+
+``PRIVATE``
+ Populates only properties for `building <Target Build Specification_>`_
+ a target.
+
+``INTERFACE``
+ Populates only properties for `using <Target Usage Requirements_>`_
+ a target.
+
+The commands are:
+
+:command:`target_compile_definitions`
+ Populates the :prop_tgt:`COMPILE_DEFINITIONS` build specification and
+ :prop_tgt:`INTERFACE_COMPILE_DEFINITIONS` usage requirement properties.
+
+ For example, the call
+
+ .. code-block:: cmake
+
+ target_compile_definitions(archive
+ PRIVATE BUILDING_WITH_LZMA
+ INTERFACE USING_ARCHIVE_LIB
+ )
+
+ appends ``BUILDING_WITH_LZMA`` to the target's ``COMPILE_DEFINITIONS``
+ property and appends ``USING_ARCHIVE_LIB`` to the target's
+ ``INTERFACE_COMPILE_DEFINITIONS`` property.
+
+:command:`target_compile_options`
+ Populates the :prop_tgt:`COMPILE_OPTIONS` build specification and
+ :prop_tgt:`INTERFACE_COMPILE_OPTIONS` usage requirement properties.
+
+:command:`target_compile_features`
+ .. versionadded:: 3.1
+
+ Populates the :prop_tgt:`COMPILE_FEATURES` build specification and
+ :prop_tgt:`INTERFACE_COMPILE_FEATURES` usage requirement properties.
+
+:command:`target_include_directories`
+ Populates the :prop_tgt:`INCLUDE_DIRECTORIES` build specification
+ and :prop_tgt:`INTERFACE_INCLUDE_DIRECTORIES` usage requirement
+ properties. With the ``SYSTEM`` option, it also populates the
+ :prop_tgt:`INTERFACE_SYSTEM_INCLUDE_DIRECTORIES` usage requirement.
+
+ For convenience, the :variable:`CMAKE_INCLUDE_CURRENT_DIR` variable
+ may be enabled to add the source directory and corresponding build
+ directory as ``INCLUDE_DIRECTORIES`` on all targets. Similarly,
+ the :variable:`CMAKE_INCLUDE_CURRENT_DIR_IN_INTERFACE` variable may
+ be enabled to add them as ``INTERFACE_INCLUDE_DIRECTORIES`` on all
+ targets.
+
+:command:`target_sources`
+ .. versionadded:: 3.1
+
+ Populates the :prop_tgt:`SOURCES` build specification and
+ :prop_tgt:`INTERFACE_SOURCES` usage requirement properties.
+
+ It also supports specifying :ref:`File Sets`, which can add C++ module
+ sources and headers not listed in the ``SOURCES`` and ``INTERFACE_SOURCES``
+ properties. File sets may also populate the :prop_tgt:`INCLUDE_DIRECTORIES`
+ build specification and :prop_tgt:`INTERFACE_INCLUDE_DIRECTORIES` usage
+ requirement properties with the include directories containing the headers.
+
+:command:`target_precompile_headers`
+ .. versionadded:: 3.16
+
+ Populates the :prop_tgt:`PRECOMPILE_HEADERS` build specification and
+ :prop_tgt:`INTERFACE_PRECOMPILE_HEADERS` usage requirement properties.
+
+:command:`target_link_libraries`
+ Populates the :prop_tgt:`LINK_LIBRARIES` build specification
+ and :prop_tgt:`INTERFACE_LINK_LIBRARIES` usage requirement properties.
+
+ This is the primary mechanism by which link dependencies and their
+ `usage requirements <Target Usage Requirements_>`_ are transitively
+ propagated to affect compilation and linking of a target.
+
+:command:`target_link_directories`
+ .. versionadded:: 3.13
+
+ Populates the :prop_tgt:`LINK_DIRECTORIES` build specification and
+ :prop_tgt:`INTERFACE_LINK_DIRECTORIES` usage requirement properties.
+
+:command:`target_link_options`
+ .. versionadded:: 3.13
+
+ Populates the :prop_tgt:`LINK_OPTIONS` build specification and
+ :prop_tgt:`INTERFACE_LINK_OPTIONS` usage requirement properties.
+
+.. _`Target Build Specification`:
+
+Target Build Specification
+--------------------------
+
+The build specification of `Binary Targets`_ is represented by target
+properties. For each of the following `build <Target Build Properties_>`_
+and `link <Target Link Properties_>`_ properties, compilation and linking
+of the target is affected both by its own value and by the corresponding
+`usage requirement <Target Usage Requirements_>`_ property, named with
+an ``INTERFACE_`` prefix, collected from the transitive closure of link
+dependencies.
+
+.. _`Target Build Properties`:
+
+Target Build Properties
+^^^^^^^^^^^^^^^^^^^^^^^
+
+:prop_tgt:`COMPILE_DEFINITIONS`
+ List of compile definitions for compiling sources in the target.
+ These are passed to the compiler with ``-D`` flags, or equivalent,
+ in an unspecified order.
+
+ The :prop_tgt:`DEFINE_SYMBOL` target property is also used
+ as a compile definition as a special convenience case for
+ ``SHARED`` and ``MODULE`` library targets.
+
+:prop_tgt:`COMPILE_OPTIONS`
+ List of compile options for compiling sources in the target.
+ These are passed to the compiler as flags, in the order of appearance.
+
+ Compile options are automatically escaped for the shell.
+
+ Some compile options are best specified via dedicated settings,
+ such as the :prop_tgt:`POSITION_INDEPENDENT_CODE` target property.
+
+:prop_tgt:`COMPILE_FEATURES`
+ .. versionadded:: 3.1
+
+ List of :manual:`compile features <cmake-compile-features(7)>` needed
+ for compiling sources in the target. Typically these ensure the
+ target's sources are compiled using a sufficient language standard level.
+
+:prop_tgt:`INCLUDE_DIRECTORIES`
+ List of include directories for compiling sources in the target.
+ These are passed to the compiler with ``-I`` or ``-isystem`` flags,
+ or equivalent, in the order of appearance.
+
+ For convenience, the :variable:`CMAKE_INCLUDE_CURRENT_DIR` variable
+ may be enabled to add the source directory and corresponding build
+ directory as ``INCLUDE_DIRECTORIES`` on all targets.
+
+:prop_tgt:`SOURCES`
+ List of source files associated with the target. This includes sources
+ specified when the target was created by the :command:`add_executable`,
+ :command:`add_library`, or :command:`add_custom_target` command.
+ It also includes sources added by the :command:`target_sources` command,
+ but does not include :ref:`File Sets`.
+
+:prop_tgt:`PRECOMPILE_HEADERS`
+ .. versionadded:: 3.16
+
+ List of header files to precompile and include when compiling
+ sources in the target.
+
+:prop_tgt:`AUTOMOC_MACRO_NAMES`
+ .. versionadded:: 3.10
+
+ List of macro names used by :prop_tgt:`AUTOMOC` to determine if a
+ C++ source in the target needs to be processed by ``moc``.
+
+:prop_tgt:`AUTOUIC_OPTIONS`
+ .. versionadded:: 3.0
+
+ List of options used by :prop_tgt:`AUTOUIC` when invoking ``uic``
+ for the target.
+
+.. _`Target Link Properties`:
+
+Target Link Properties
+^^^^^^^^^^^^^^^^^^^^^^
+
+:prop_tgt:`LINK_LIBRARIES`
+ List of link libraries for linking the target, if it is an executable,
+ shared library, or module library. Entries for `Normal Libraries`_ are
+ passed to the linker either via paths to their link artifacts, or
+ with ``-l`` flags or equivalent. Entries for `Object Libraries`_ are
+ passed to the linker via paths to their object files.
+
+ Additionally, for compiling and linking the target itself,
+ `usage requirements <Target Usage Requirements_>`_ are propagated from
+ ``LINK_LIBRARIES`` entries naming `Normal Libraries`_,
+ `Interface Libraries`_, `Object Libraries`_, and `Imported Targets`_,
+ collected over the transitive closure of their
+ :prop_tgt:`INTERFACE_LINK_LIBRARIES` properties.
+
+:prop_tgt:`LINK_DIRECTORIES`
+ .. versionadded:: 3.13
+
+ List of link directories for linking the target, if it is an executable,
+ shared library, or module library. The directories are passed to the
+ linker with ``-L`` flags, or equivalent.
+
+:prop_tgt:`LINK_OPTIONS`
+ .. versionadded:: 3.13
+
+ List of link options for linking the target, if it is an executable,
+ shared library, or module library. The options are passed to the
+ linker as flags, in the order of appearance.
+
+ Link options are automatically escaped for the shell.
+
+:prop_tgt:`LINK_DEPENDS`
+ List of files on which linking the target depends, if it is an executable,
+ shared library, or module library. For example, linker scripts specified
+ via :prop_tgt:`LINK_OPTIONS` may be listed here such that changing them
+ causes binaries to be linked again.
+
+.. _`Target Usage Requirements`:
+
+Target Usage Requirements
+-------------------------
+
+The *usage requirements* of a target are settings that propagate to consumers,
+which link to the target via :command:`target_link_libraries`, in order to
+correctly compile and link with it. They are represented by transitive
+`build <Transitive Build Properties_>`_ and
+`link <Transitive Link Properties_>`_ properties.
Note that usage requirements are not designed as a way to make downstreams
-use particular :prop_tgt:`COMPILE_OPTIONS` or
-:prop_tgt:`COMPILE_DEFINITIONS` etc for convenience only. The contents of
-the properties must be **requirements**, not merely recommendations or
-convenience.
+use particular :prop_tgt:`COMPILE_OPTIONS`, :prop_tgt:`COMPILE_DEFINITIONS`,
+etc. for convenience only. The contents of the properties must be
+**requirements**, not merely recommendations.
See the :ref:`Creating Relocatable Packages` section of the
:manual:`cmake-packages(7)` manual for discussion of additional care
that must be taken when specifying usage requirements while creating
packages for redistribution.
-Target Properties
------------------
-
-The contents of the :prop_tgt:`INCLUDE_DIRECTORIES`,
-:prop_tgt:`COMPILE_DEFINITIONS` and :prop_tgt:`COMPILE_OPTIONS` target
-properties are used appropriately when compiling the source files of a
-binary target.
-
-Entries in the :prop_tgt:`INCLUDE_DIRECTORIES` are added to the compile line
-with ``-I`` or ``-isystem`` prefixes and in the order of appearance in the
-property value.
-
-Entries in the :prop_tgt:`COMPILE_DEFINITIONS` are prefixed with ``-D`` or
-``/D`` and added to the compile line in an unspecified order. The
-:prop_tgt:`DEFINE_SYMBOL` target property is also added as a compile
-definition as a special convenience case for ``SHARED`` and ``MODULE``
-library targets.
-
-Entries in the :prop_tgt:`COMPILE_OPTIONS` are escaped for the shell and added
-in the order of appearance in the property value. Several compile options have
-special separate handling, such as :prop_tgt:`POSITION_INDEPENDENT_CODE`.
-
-The contents of the :prop_tgt:`INTERFACE_INCLUDE_DIRECTORIES`,
-:prop_tgt:`INTERFACE_COMPILE_DEFINITIONS` and
-:prop_tgt:`INTERFACE_COMPILE_OPTIONS` target properties are
-*Usage Requirements* -- they specify content which consumers
-must use to correctly compile and link with the target they appear on.
-For any binary target, the contents of each ``INTERFACE_`` property on
-each target specified in a :command:`target_link_libraries` command is
-consumed:
-
-.. code-block:: cmake
-
- set(srcs archive.cpp zip.cpp)
- if (LZMA_FOUND)
- list(APPEND srcs lzma.cpp)
- endif()
- add_library(archive SHARED ${srcs})
- if (LZMA_FOUND)
- # The archive library sources are compiled with -DBUILDING_WITH_LZMA
- target_compile_definitions(archive PRIVATE BUILDING_WITH_LZMA)
- endif()
- target_compile_definitions(archive INTERFACE USING_ARCHIVE_LIB)
-
- add_executable(consumer)
- # Link consumer to archive and consume its usage requirements. The consumer
- # executable sources are compiled with -DUSING_ARCHIVE_LIB.
- target_link_libraries(consumer archive)
-
-Because it is common to require that the source directory and corresponding
-build directory are added to the :prop_tgt:`INCLUDE_DIRECTORIES`, the
-:variable:`CMAKE_INCLUDE_CURRENT_DIR` variable can be enabled to conveniently
-add the corresponding directories to the :prop_tgt:`INCLUDE_DIRECTORIES` of
-all targets. The variable :variable:`CMAKE_INCLUDE_CURRENT_DIR_IN_INTERFACE`
-can be enabled to add the corresponding directories to the
-:prop_tgt:`INTERFACE_INCLUDE_DIRECTORIES` of all targets. This makes use of
-targets in multiple different directories convenient through use of the
-:command:`target_link_libraries` command.
-
-
-.. _`Target Usage Requirements`:
-
-Transitive Usage Requirements
------------------------------
-
The usage requirements of a target can transitively propagate to the dependents.
The :command:`target_link_libraries` command has ``PRIVATE``,
``INTERFACE`` and ``PUBLIC`` keywords to control the propagation.
@@ -329,6 +505,91 @@
which will be exported for installation using the :command:`install(EXPORT)`
command. See :ref:`Creating Packages` for more.
+.. _`Transitive Build Properties`:
+
+Transitive Build Properties
+^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+:prop_tgt:`INTERFACE_COMPILE_DEFINITIONS`
+ List of compile definitions for compiling sources in the target's consumers.
+ Typically these are used by the target's header files.
+
+:prop_tgt:`INTERFACE_COMPILE_OPTIONS`
+ List of compile options for compiling sources in the target's consumers.
+
+:prop_tgt:`INTERFACE_COMPILE_FEATURES`
+ .. versionadded:: 3.1
+
+ List of :manual:`compile features <cmake-compile-features(7)>` needed
+ for compiling sources in the target's consumers. Typically these
+ ensure the target's header files are processed when compiling consumers
+ using a sufficient language standard level.
+
+:prop_tgt:`INTERFACE_INCLUDE_DIRECTORIES`
+ List of include directories for compiling sources in the target's consumers.
+ Typically these are the locations of the target's header files.
+
+:prop_tgt:`INTERFACE_SYSTEM_INCLUDE_DIRECTORIES`
+ List of directories that, when specified as include directories, e.g., by
+ :prop_tgt:`INCLUDE_DIRECTORIES` or :prop_tgt:`INTERFACE_INCLUDE_DIRECTORIES`,
+ should be treated as "system" include directories when compiling sources
+ in the target's consumers.
+
+:prop_tgt:`INTERFACE_SOURCES`
+ List of source files to associate with the target's consumers.
+
+:prop_tgt:`INTERFACE_PRECOMPILE_HEADERS`
+ .. versionadded:: 3.16
+
+ List of header files to precompile and include when compiling
+ sources in the target's consumers.
+
+:prop_tgt:`INTERFACE_AUTOMOC_MACRO_NAMES`
+ .. versionadded:: 3.27
+
+ List of macro names used by :prop_tgt:`AUTOMOC` to determine if a
+ C++ source in the target's consumers needs to be processed by ``moc``.
+
+:prop_tgt:`INTERFACE_AUTOUIC_OPTIONS`
+ .. versionadded:: 3.0
+
+ List of options used by :prop_tgt:`AUTOUIC` when invoking ``uic``
+ for the target's consumers.
+
+.. _`Transitive Link Properties`:
+
+Transitive Link Properties
+^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+:prop_tgt:`INTERFACE_LINK_LIBRARIES`
+ List of link libraries for linking the target's consumers, for
+ those that are executables, shared libraries, or module libraries.
+ These are the transitive dependencies of the target.
+
+ Additionally, for compiling and linking the target's consumers,
+ `usage requirements <Target Usage Requirements_>`_ are collected from
+ the transitive closure of ``INTERFACE_LINK_LIBRARIES`` entries naming
+ `Normal Libraries`_, `Interface Libraries`_, `Object Libraries`_,
+ and `Imported Targets`_,
+
+:prop_tgt:`INTERFACE_LINK_DIRECTORIES`
+ .. versionadded:: 3.13
+
+ List of link directories for linking the target's consumers, for
+ those that are executables, shared libraries, or module libraries.
+
+:prop_tgt:`INTERFACE_LINK_OPTIONS`
+ .. versionadded:: 3.13
+
+ List of link options for linking the target's consumers, for
+ those that are executables, shared libraries, or module libraries.
+
+:prop_tgt:`INTERFACE_LINK_DEPENDS`
+ .. versionadded:: 3.13
+
+ List of files on which linking the target's consumers depends, for
+ those that are executables, shared libraries, or module libraries.
+
.. _`Compatible Interface Properties`:
Compatible Interface Properties
diff --git a/Help/manual/cmake-developer.7.rst b/Help/manual/cmake-developer.7.rst
index a09bd14..cebe8f9 100644
--- a/Help/manual/cmake-developer.7.rst
+++ b/Help/manual/cmake-developer.7.rst
@@ -119,7 +119,8 @@
The more modern approach is to behave as much like
:ref:`config file packages <Config File Packages>` files as possible, by
providing :ref:`imported target <Imported targets>`. This has the advantage
-of propagating :ref:`Target Usage Requirements` to consumers.
+of propagating :ref:`usage requirements <Target Usage Requirements>`
+to consumers.
In either case (or even when providing both variables and imported
targets), find modules should provide backwards compatibility with old
diff --git a/Help/manual/cmake-generator-expressions.7.rst b/Help/manual/cmake-generator-expressions.7.rst
index 0f09218..e2a99c3 100644
--- a/Help/manual/cmake-generator-expressions.7.rst
+++ b/Help/manual/cmake-generator-expressions.7.rst
@@ -1281,7 +1281,8 @@
.. versionadded:: 3.27
- Content of ``...``, when collecting :ref:`Target Usage Requirements`,
+ Content of ``...``, when collecting
+ :ref:`usage requirements <Target Usage Requirements>`,
otherwise it is the empty string. This is intended for use in an
:prop_tgt:`INTERFACE_LINK_LIBRARIES` and :prop_tgt:`LINK_LIBRARIES` target
properties, typically populated via the :command:`target_link_libraries` command.
@@ -1669,7 +1670,8 @@
.. versionadded:: 3.1
- Content of ``...``, except while collecting :ref:`Target Usage Requirements`,
+ Content of ``...``, except while collecting
+ :ref:`usage requirements <Target Usage Requirements>`,
in which case it is the empty string. This is intended for use in an
:prop_tgt:`INTERFACE_LINK_LIBRARIES` target property, typically populated
via the :command:`target_link_libraries` command, to specify private link
@@ -1746,7 +1748,8 @@
expression is evaluated on.
.. versionchanged:: 3.26
- When encountered during evaluation of :ref:`Target Usage Requirements`,
+ When encountered during evaluation of
+ :ref:`usage requirements <Target Usage Requirements>`,
typically in an ``INTERFACE_*`` target property, lookup of the ``tgt``
name occurs in the directory of the target specifying the requirement,
rather than the directory of the consuming target for which the
@@ -1757,8 +1760,8 @@
Value of the property ``prop`` on the target for which the expression
is being evaluated. Note that for generator expressions in
- :ref:`Target Usage Requirements` this is the consuming target rather
- than the target specifying the requirement.
+ :ref:`usage requirements <Target Usage Requirements>` this is the
+ consuming target rather than the target specifying the requirement.
.. genex:: $<TARGET_OBJECTS:tgt>
diff --git a/Help/prop_tgt/AUTOUIC_OPTIONS.rst b/Help/prop_tgt/AUTOUIC_OPTIONS.rst
index 425ea1c..d601740 100644
--- a/Help/prop_tgt/AUTOUIC_OPTIONS.rst
+++ b/Help/prop_tgt/AUTOUIC_OPTIONS.rst
@@ -1,6 +1,8 @@
AUTOUIC_OPTIONS
---------------
+.. versionadded:: 3.0
+
Additional options for ``uic`` when using :prop_tgt:`AUTOUIC`
This property holds additional command line options which will be used when
diff --git a/Help/prop_tgt/INTERFACE_AUTOUIC_OPTIONS.rst b/Help/prop_tgt/INTERFACE_AUTOUIC_OPTIONS.rst
index e97d293..2fe011a 100644
--- a/Help/prop_tgt/INTERFACE_AUTOUIC_OPTIONS.rst
+++ b/Help/prop_tgt/INTERFACE_AUTOUIC_OPTIONS.rst
@@ -1,6 +1,8 @@
INTERFACE_AUTOUIC_OPTIONS
-------------------------
+.. versionadded:: 3.0
+
List of interface options to pass to uic.
Targets may populate this property to publish the options
diff --git a/Help/prop_tgt/LANG_STANDARD.rst b/Help/prop_tgt/LANG_STANDARD.rst
index c83da01..4b59af7 100644
--- a/Help/prop_tgt/LANG_STANDARD.rst
+++ b/Help/prop_tgt/LANG_STANDARD.rst
@@ -18,7 +18,7 @@
Note that the actual language standard used may be higher than that specified
by ``<LANG>_STANDARD``, regardless of the value of
:prop_tgt:`<LANG>_STANDARD_REQUIRED`. In particular,
-:ref:`transitive usage requirements <Target Usage Requirements>` or the use of
+:ref:`usage requirements <Target Usage Requirements>` or the use of
:manual:`compile features <cmake-compile-features(7)>` can raise the required
language standard above what ``<LANG>_STANDARD`` specifies.
diff --git a/Help/prop_tgt/LANG_STANDARD_REQUIRED.rst b/Help/prop_tgt/LANG_STANDARD_REQUIRED.rst
index e61125b..532057b 100644
--- a/Help/prop_tgt/LANG_STANDARD_REQUIRED.rst
+++ b/Help/prop_tgt/LANG_STANDARD_REQUIRED.rst
@@ -20,7 +20,7 @@
Note that the actual language standard used may be higher than that specified
by :prop_tgt:`<LANG>_STANDARD`, regardless of the value of
``<LANG>_STANDARD_REQUIRED``. In particular,
-:ref:`transitive usage requirements <Target Usage Requirements>` or the use of
+:ref:`usage requirements <Target Usage Requirements>` or the use of
:manual:`compile features <cmake-compile-features(7)>` can raise the required
language standard above what :prop_tgt:`<LANG>_STANDARD` specifies.
diff --git a/Modules/FindCUDAToolkit.cmake b/Modules/FindCUDAToolkit.cmake
index bc17f19..44d09f5 100644
--- a/Modules/FindCUDAToolkit.cmake
+++ b/Modules/FindCUDAToolkit.cmake
@@ -439,7 +439,7 @@
nvidia-ML
"""""""""
-The `NVIDIA Management Library <https://developer.nvidia.com/nvidia-management-library-nvml>`_.
+The `NVIDIA Management Library <https://developer.nvidia.com/management-library-nvml>`_.
This is a shared library only.
Targets Created:
diff --git a/Source/CMakeVersion.cmake b/Source/CMakeVersion.cmake
index 0dc7d96..645827e 100644
--- a/Source/CMakeVersion.cmake
+++ b/Source/CMakeVersion.cmake
@@ -1,7 +1,7 @@
# CMake version number components.
set(CMake_VERSION_MAJOR 3)
set(CMake_VERSION_MINOR 29)
-set(CMake_VERSION_PATCH 20240424)
+set(CMake_VERSION_PATCH 20240425)
#set(CMake_VERSION_RC 0)
set(CMake_VERSION_IS_DIRTY 0)
diff --git a/Source/cmGlobalXCodeGenerator.cxx b/Source/cmGlobalXCodeGenerator.cxx
index 7dd5ffa..8067694 100644
--- a/Source/cmGlobalXCodeGenerator.cxx
+++ b/Source/cmGlobalXCodeGenerator.cxx
@@ -1095,7 +1095,7 @@
bool& keepLastKnownFileType, const std::vector<std::string>& enabled_langs)
{
std::string ext = cmSystemTools::LowerCase(_ext);
- std::string sourcecode = "sourcecode";
+ std::string sourcecode = "default";
if (ext == "o"_s) {
keepLastKnownFileType = true;
@@ -1110,42 +1110,42 @@
sourcecode = "file.storyboard";
// NOLINTNEXTLINE(bugprone-branch-clone)
} else if (ext == "mm"_s && !cm::contains(enabled_langs, "OBJCXX")) {
- sourcecode += ".cpp.objcpp";
+ sourcecode = "sourcecode.cpp.objcpp";
// NOLINTNEXTLINE(bugprone-branch-clone)
} else if (ext == "m"_s && !cm::contains(enabled_langs, "OBJC")) {
- sourcecode += ".c.objc";
+ sourcecode = "sourcecode.c.objc";
} else if (ext == "swift"_s) {
- sourcecode += ".swift";
+ sourcecode = "sourcecode.swift";
} else if (ext == "plist"_s) {
- sourcecode += ".text.plist";
+ sourcecode = "sourcecode.text.plist";
} else if (ext == "h"_s) {
- sourcecode += ".c.h";
+ sourcecode = "sourcecode.c.h";
} else if (ext == "hxx"_s || ext == "hpp"_s || ext == "txx"_s ||
ext == "pch"_s || ext == "hh"_s || ext == "inl"_s) {
- sourcecode += ".cpp.h";
+ sourcecode = "sourcecode.cpp.h";
} else if (ext == "png"_s || ext == "gif"_s || ext == "jpg"_s) {
keepLastKnownFileType = true;
sourcecode = "image";
} else if (ext == "txt"_s) {
- sourcecode += ".text";
+ sourcecode = "sourcecode.text";
} else if (lang == "CXX"_s) {
- sourcecode += ".cpp.cpp";
+ sourcecode = "sourcecode.cpp.cpp";
} else if (lang == "C"_s) {
- sourcecode += ".c.c";
+ sourcecode = "sourcecode.c.c";
} else if (lang == "OBJCXX"_s) {
- sourcecode += ".cpp.objcpp";
+ sourcecode = "sourcecode.cpp.objcpp";
} else if (lang == "OBJC"_s) {
- sourcecode += ".c.objc";
+ sourcecode = "sourcecode.c.objc";
} else if (lang == "Fortran"_s) {
- sourcecode += ".fortran.f90";
+ sourcecode = "sourcecode.fortran.f90";
} else if (lang == "ASM"_s) {
- sourcecode += ".asm";
+ sourcecode = "sourcecode.asm";
} else if (ext == "metal"_s) {
- sourcecode += ".metal";
+ sourcecode = "sourcecode.metal";
} else if (ext == "mig"_s) {
- sourcecode += ".mig";
+ sourcecode = "sourcecode.mig";
} else if (ext == "tbd"_s) {
- sourcecode += ".text-based-dylib-definition";
+ sourcecode = "sourcecode.text-based-dylib-definition";
} else if (ext == "a"_s) {
keepLastKnownFileType = true;
sourcecode = "archive.ar";
diff --git a/Source/cmNinjaTargetGenerator.cxx b/Source/cmNinjaTargetGenerator.cxx
index e2642b2..c52a012 100644
--- a/Source/cmNinjaTargetGenerator.cxx
+++ b/Source/cmNinjaTargetGenerator.cxx
@@ -1992,6 +1992,11 @@
std::string const moduleFilepath =
this->ConvertToNinjaPath(cmStrCat(moduleDirectory, '/', moduleFilename));
+ vars.emplace("description",
+ cmStrCat("Building Swift Module '", moduleName, "' with ",
+ sources.size(),
+ sources.size() == 1 ? " source" : " sources"));
+
bool const isSingleOutput = [this, compileMode]() -> bool {
bool isMultiThread = false;
if (cmValue numThreadStr =
diff --git a/Tests/RunCMake/Swift/IncrementalSwift-second-stdout.txt b/Tests/RunCMake/Swift/IncrementalSwift-second-stdout.txt
index 8e5b97c..ccd8aee 100644
--- a/Tests/RunCMake/Swift/IncrementalSwift-second-stdout.txt
+++ b/Tests/RunCMake/Swift/IncrementalSwift-second-stdout.txt
@@ -1,3 +1,3 @@
-.*Building Swift object A.swiftmodule CMakeFiles(/|\\)A.dir(/|\\)a.swift.o(bj)?
-.*Building Swift object B.swiftmodule CMakeFiles(/|\\)B.dir(/|\\)b.swift.o(bj)?
+.*Building Swift Module 'A' with 1 source
+.*Building Swift Module 'B' with 1 source
FAILED: B.swiftmodule CMakeFiles(/|\\)B.dir(/|\\)b.swift.o(bj)?
diff --git a/Tests/RunCMake/XcodeProject/XcodeFileType-check.cmake b/Tests/RunCMake/XcodeProject/XcodeFileType-check.cmake
index 1847bc9..48b4680 100644
--- a/Tests/RunCMake/XcodeProject/XcodeFileType-check.cmake
+++ b/Tests/RunCMake/XcodeProject/XcodeFileType-check.cmake
@@ -1,4 +1,4 @@
-set(expect-default "explicitFileType = sourcecode")
+set(expect-default "explicitFileType = default")
set(expect-explicit "explicitFileType = sourcecode.c.h")
set(expect-lastKnown "lastKnownFileType = sourcecode.c.h")
foreach(src default explicit lastKnown)
