Help: Add documentation for runtime dependency installation

3 files changed, 120 insertions, 2 deletions

diff --git a/Help/command/install.rst b/Help/command/install.rst
index 4d41fb3..acfaa48 100644
--- a/Help/command/install.rst
+++ b/Help/command/install.rst
@@ -15,6 +15,7 @@ Synopsis
   install(`SCRIPT`_ <file> [...])
   install(`CODE`_ <code> [...])
   install(`EXPORT`_ <export-name> [...])
+  install(`RUNTIME_DEPENDENCY_SET`_ <set-name> [...])
 
 Introduction
 ^^^^^^^^^^^^
@@ -125,6 +126,7 @@ Installing Targets
 .. code-block:: cmake
 
   install(TARGETS targets... [EXPORT <export-name>]
+          [RUNTIME_DEPENDENCIES args...|RUNTIME_DEPENDENCY_SET <set-name>]
           [[ARCHIVE|LIBRARY|RUNTIME|OBJECTS|FRAMEWORK|BUNDLE|
             PRIVATE_HEADER|PUBLIC_HEADER|RESOURCE]
            [DESTINATION <dir>]
@@ -339,6 +341,34 @@ top level:
   relative path is specified, it is treated as relative to the
   ``$<INSTALL_PREFIX>``.
 
+``RUNTIME_DEPENDENCY_SET``
+  .. versionadded:: 3.21
+
+  This option causes all runtime dependencies of installed executable, shared
+  library, and module targets to be added to the specified runtime dependency
+  set. This set can then be installed later on with an
+  `install(RUNTIME_DEPENDENCY_SET)`_ command.
+
+  This argument and the ``RUNTIME_DEPENDENCIES`` argument are mutually
+  exclusive.
+
+``RUNTIME_DEPENDENCIES``
+  .. versionadded:: 3.21
+
+  This option causes all runtime dependencies of installed executable, shared
+  library, and module targets to be installed along with the targets
+  themselves. The ``RUNTIME``, ``LIBRARY``, ``FRAMEWORK``, and generic
+  arguments are used to determine the properties (``DESTINATION``,
+  ``COMPONENT``, etc.) of the installation of these dependencies.
+
+  ``RUNTIME_DEPENDENCIES`` is semantically equivalent to calling
+  ``install(TARGETS ... RUNTIME_DEPENDENCY_SET)`` and then
+  `install(RUNTIME_DEPENDENCY_SET)`_ with a randomly generated name. It accepts
+  all of the same options as `install(RUNTIME_DEPENDENCY_SET)`_.
+
+  This argument and the ``RUNTIME_DEPENDENCY_SET`` argument are mutually
+  exclusive.
+
 One or more groups of properties may be specified in a single call to
 the ``TARGETS`` form of this command.  A target may be installed more than
 once to different locations.  Consider hypothetical targets ``myExe``,
@@ -394,6 +424,7 @@ Installing Imported Runtime Artifacts
 .. code-block:: cmake
 
   install(IMPORTED_RUNTIME_ARTIFACTS targets...
+          [RUNTIME_DEPENDENCY_SET <set-name>]
           [[LIBRARY|RUNTIME|FRAMEWORK|BUNDLE]
            [DESTINATION <dir>]
            [PERMISSIONS permissions...]
@@ -415,6 +446,15 @@ not installed. In the case of :prop_tgt:`FRAMEWORK` libraries,
 :prop_tgt:`MACOSX_BUNDLE` executables, and :prop_tgt:`BUNDLE` CFBundles, the
 entire directory is installed.
 
+``IMPORTED_RUNTIME_ARTIFACTS`` accepts the following additional arguments:
+
+``RUNTIME_DEPENDENCY_SET``
+
+  This option causes all runtime dependencies of installed executable, shared
+  library, and module targets to be added to the specified runtime dependency
+  set. This set can then be installed later on with an
+  `install(RUNTIME_DEPENDENCY_SET)`_ command.
+
 Installing Files
 ^^^^^^^^^^^^^^^^
 
@@ -773,6 +813,74 @@ executable from the installation tree using the imported target name
   :command:`install_files`, and :command:`install_programs` commands
   is not defined.
 
+Installing Runtime Dependencies
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+.. _`install(RUNTIME_DEPENDENCY_SET)`:
+.. _RUNTIME_DEPENDENCY_SET:
+
+.. versionadded:: 3.21
+
+.. code-block:: cmake
+
+  install(RUNTIME_DEPENDENCY_SET <set-name>
+          [[LIBRARY|RUNTIME|FRAMEWORK]
+           [DESTINATION <dir>]
+           [PERMISSIONS permissions...]
+           [CONFIGURATIONS [Debug|Release|...]]
+           [COMPONENT <component>]
+           [NAMELINK_COMPONENT <component>]
+           [OPTIONAL] [EXCLUDE_FROM_ALL]
+          ] [...]
+          [PRE_INCLUDE_REGEXES regexes...]
+          [PRE_EXCLUDE_REGEXES regexes...]
+          [POST_INCLUDE_REGEXES regexes...]
+          [POST_EXCLUDE_REGEXES regexes...]
+          [DIRECTORIES directories...]
+          )
+
+Installs a runtime dependency set created by one or more
+`install(TARGETS)`_ or `install(IMPORTED_RUNTIME_ARTIFACTS)`_ commands. The
+dependencies of targets belonging to a runtime dependency set are installed in
+the ``RUNTIME`` destination and component on DLL platforms, and in the
+``LIBRARY`` destination and component on non-DLL platforms. macOS frameworks
+are installed in the ``FRAMEWORK`` destination and component. The generated
+install script calls :command:`file(GET_RUNTIME_DEPENDENCIES)` on the
+build-tree files to calculate the runtime dependencies, with the build-tree
+executable files as the ``EXECUTABLES`` argument, the build-tree shared
+libraries as the ``LIBRARIES`` argument, and the build-tree modules as the
+``MODULES`` argument. If one of the executables is a :prop_tgt:`MACOSX_BUNDLE`
+executable on a macOS platform, that executable is passed as the
+``BUNDLE_EXECUTABLE`` argument. If ``RUNTIME_DEPENDENCY_SET`` is specified on
+a macOS platform, at most one :prop_tgt:`MACOSX_BUNDLE` executable may be in
+the runtime dependency set. The :prop_tgt:`MACOSX_BUNDLE` property has no
+effect on non-macOS platforms. Targets built within the build tree will never
+be installed as runtime dependencies, nor will their own dependencies, unless
+the targets themselves are installed with `install(TARGETS)`_.
+
+This argument accepts the following sub-arguments:
+
+``DIRECTORIES <directories>``
+  List of directories to be passed as the ``DIRECTORIES`` argument of
+  :command:`file(GET_RUNTIME_DEPENDENCIES)`. This argument supports
+  :manual:`generator expressions <cmake-generator-expressions(7)>`. If a
+  ``DIRECTORIES`` argument evaluates to an empty string, it is not passed to
+  :command:`file(GET_RUNTIME_DEPENDENCIES)`.
+
+``PRE_INCLUDE_REGEXES <regexes>``, ``PRE_EXCLUDE_REGEXES <regexes>``, ``POST_INCLUDE_REGEXES <regexes>``, ``POST_EXCLUDE_REGEXES <regexes>``
+  List of regular expressions to be passed as their respective arguments to
+  :command:`file(GET_RUNTIME_DEPENDENCIES)`. These arguments support
+  :manual:`generator expressions <cmake-generator-expressions(7)>`. If an
+  argument evaluates to an empty string, it is not passed to
+  :command:`file(GET_RUNTIME_DEPENDENCIES)`.
+
+``POST_INCLUDE_FILES <files>``, ``POST_EXCLUDE_FILES <files>``
+  List of files to be passed as their respective arguments to
+  :command:`file(GET_RUNTIME_DEPENDENCIES)`. These arguments support
+  :manual:`generator expressions <cmake-generator-expressions(7)>`. If an
+  argument evaluates to an empty string, it is not passed to
+  :command:`file(GET_RUNTIME_DEPENDENCIES)`.
+
 Generated Installation Script
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
diff --git a/Help/manual/cmake-generator-expressions.7.rst b/Help/manual/cmake-generator-expressions.7.rst
index 775067a..0ba41c8 100644
--- a/Help/manual/cmake-generator-expressions.7.rst
+++ b/Help/manual/cmake-generator-expressions.7.rst
@@ -966,8 +966,9 @@ which is just the string ``tgt``.
 .. genex:: $<INSTALL_PREFIX>
 
   Content of the install prefix when the target is exported via
-  :command:`install(EXPORT)`, or when evaluated in
-  :prop_tgt:`INSTALL_NAME_DIR`, and empty otherwise.
+  :command:`install(EXPORT)`, or when evaluated in the
+  :prop_tgt:`INSTALL_NAME_DIR` property or the ``INSTALL_NAME_DIR`` argument of
+  :command:`install(RUNTIME_DEPENDENCY_SET)`, and empty otherwise.
 
 Output-Related Expressions
 --------------------------
diff --git a/Help/release/dev/install-runtime-dependencies.rst b/Help/release/dev/install-runtime-dependencies.rst
new file mode 100644
index 0000000..58c92e6
--- /dev/null
+++ b/Help/release/dev/install-runtime-dependencies.rst
@@ -0,0 +1,9 @@
+install-runtime-dependencies
+----------------------------
+
+* The :command:`install(TARGETS)` command gained new ``RUNTIME_DEPENDENCIES``
+  and ``RUNTIME_DEPENDENCY_SET`` arguments, which can be used to install
+  runtime dependencies using :command:`file(GET_RUNTIME_DEPENDENCIES)`.
+* The :command:`install` command gained a new ``RUNTIME_DEPENDENCY_SET`` mode,
+  which can be used to install runtime dependencies using
+  :command:`file(GET_RUNTIME_DEPENDENCIES)`.