Merge topic 'install-with-runtime-dependencies'

8d898cb3e1 FileAPI: Add integration for runtime dependency installers
72f2448e82 Help: Add documentation for runtime dependency installation
0c3c6acaff Tests: Add tests for new options
4910132d8c install: Add RUNTIME_DEPENDENCY_SET mode
bc8a4a06a4 install(IMPORTED_RUNTIME_ARTIFACTS): Add RUNTIME_DEPENDENCY_SET option
3e7d3c252a install(TARGETS): Add RUNTIME_DEPENDENCY_SET argument
ed3633d88c install(TARGETS): Add RUNTIME_DEPENDENCIES option
f2617cf8e6 Source: Add cmInstallRuntimeDependencySet
...

Acked-by: Kitware Robot <kwrobot@kitware.com>
Merge-request: !6186

4 files changed, 144 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-file-api.7.rst b/Help/manual/cmake-file-api.7.rst
index e7d78c3..5e22ea9 100644
--- a/Help/manual/cmake-file-api.7.rst
+++ b/Help/manual/cmake-file-api.7.rst
@@ -752,6 +752,12 @@ with members:
       The ``destination`` member is populated. The ``isOptional`` member may
       exist. This type has no additional members.
 
+    ``runtimeDependencySet``
+      An :command:`install(RUNTIME_DEPENDENCY_SET)` call or an
+      :command:`install(TARGETS)` call with ``RUNTIME_DEPENDENCIES``. The
+      ``destination`` member is populated. This type has additional members
+      ``runtimeDependencySetName`` and ``runtimeDependencySetType``.
+
   ``isExcludeFromAll``
     Optional member that is present with boolean value ``true`` when
     :command:`install` is called with the ``EXCLUDE_FROM_ALL`` option.
@@ -811,6 +817,24 @@ with members:
       An unsigned integer 0-based index into the main "codemodel"
       object's ``targets`` array for the target.
 
+  ``runtimeDependencySetName``
+    Optional member that is present when ``type`` is ``runtimeDependencySet``
+    and the installer was created by an
+    :command:`install(RUNTIME_DEPENDENCY_SET)` call. The value is a string
+    specifying the name of the runtime dependency set that was installed.
+
+  ``runtimeDependencySetType``
+    Optional member that is present when ``type`` is ``runtimeDependencySet``.
+    The value is a string with one of the following values:
+
+    ``library``
+      Indicates that this installer installs dependencies that are not macOS
+      frameworks.
+
+    ``framework``
+      Indicates that this installer installs dependencies that are macOS
+      frameworks.
+
   ``scriptFile``
     Optional member that is present when ``type`` is ``script``.
     The value is a string specifying the path to the script file on disk,
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)`.