Merge topic 'install-imported-runtime-artifacts'

f7ba3a0589 FileAPI: Populate information for IMPORTED_RUNTIME_ARTIFACTS
df7040a271 install(): Add IMPORTED_RUNTIME_ARTIFACTS mode
60e752ced8 Refactor: Move common methods into cmInstallGenerator

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

3 files changed, 43 insertions, 0 deletions

diff --git a/Help/command/install.rst b/Help/command/install.rst
index 2259176..2865e1d 100644
--- a/Help/command/install.rst
+++ b/Help/command/install.rst
@@ -9,6 +9,7 @@ Synopsis
 .. parsed-literal::
 
   install(`TARGETS`_ <target>... [...])
+  install(`IMPORTED_RUNTIME_ARTIFACTS`_ <target>... [...])
   install({`FILES`_ | `PROGRAMS`_} <file>... [...])
   install(`DIRECTORY`_ <dir>... [...])
   install(`SCRIPT`_ <file> [...])
@@ -382,6 +383,38 @@ set to ``TRUE`` has undefined behavior.
   to ensure that such out-of-directory targets are built before the
   subdirectory-specific install rules are run.
 
+Installing Imported Runtime Artifacts
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+.. _`install(IMPORTED_RUNTIME_ARTIFACTS)`:
+.. _IMPORTED_RUNTIME_ARTIFACTS:
+
+.. versionadded:: 3.21
+
+.. code-block:: cmake
+
+  install(IMPORTED_RUNTIME_ARTIFACTS targets...
+          [[LIBRARY|RUNTIME|FRAMEWORK|BUNDLE]
+           [DESTINATION <dir>]
+           [PERMISSIONS permissions...]
+           [CONFIGURATIONS [Debug|Release|...]]
+           [COMPONENT <component>]
+           [OPTIONAL] [EXCLUDE_FROM_ALL]
+          ] [...]
+          )
+
+The ``IMPORTED_RUNTIME_ARTIFACTS`` form specifies rules for installing the
+runtime artifacts of imported targets. Projects may do this if they want to
+bundle outside executables or modules inside their installation. The
+``LIBRARY``, ``RUNTIME``, ``FRAMEWORK``, and ``BUNDLE`` arguments have the
+same semantics that they do in the `TARGETS`_ mode. Only the runtime artifacts
+of imported targets are installed (except in the case of :prop_tgt:`FRAMEWORK`
+libraries, :prop_tgt:`MACOSX_BUNDLE` executables, and :prop_tgt:`BUNDLE`
+CFBundles.) For example, headers and import libraries associated with DLLs are
+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.
+
 Installing Files
 ^^^^^^^^^^^^^^^^
 
diff --git a/Help/manual/cmake-file-api.7.rst b/Help/manual/cmake-file-api.7.rst
index 0e530bc..e7d78c3 100644
--- a/Help/manual/cmake-file-api.7.rst
+++ b/Help/manual/cmake-file-api.7.rst
@@ -747,6 +747,11 @@ with members:
       An :command:`install(CODE)` call.
       This type has no additional members.
 
+    ``importedRuntimeArtifacts``
+      An :command:`install(IMPORTED_RUNTIME_ARTIFACTS)` call.
+      The ``destination`` member is populated. The ``isOptional`` member may
+      exist. This type has no additional members.
+
   ``isExcludeFromAll``
     Optional member that is present with boolean value ``true`` when
     :command:`install` is called with the ``EXCLUDE_FROM_ALL`` option.
diff --git a/Help/release/dev/install-imported-runtime-artifacts.rst b/Help/release/dev/install-imported-runtime-artifacts.rst
new file mode 100644
index 0000000..e2821c1
--- /dev/null
+++ b/Help/release/dev/install-imported-runtime-artifacts.rst
@@ -0,0 +1,5 @@
+install-imported-runtime-artifacts
+----------------------------------
+
+* The :command:`install` command gained a new ``IMPORTED_RUNTIME_ARTIFACTS``
+  mode, which can be used to install the runtime artifacts of imported targets.