summaryrefslogtreecommitdiff
path: root/Help/command/install.rst
diff options
context:
space:
mode:
Diffstat (limited to 'Help/command/install.rst')
-rw-r--r--Help/command/install.rst162
1 files changed, 159 insertions, 3 deletions
diff --git a/Help/command/install.rst b/Help/command/install.rst
index 35207f4c4..c6af4897e 100644
--- a/Help/command/install.rst
+++ b/Help/command/install.rst
@@ -9,11 +9,13 @@ Synopsis
.. parsed-literal::
install(`TARGETS`_ <target>... [...])
+ install(`IMPORTED_RUNTIME_ARTIFACTS`_ <target>... [...])
install({`FILES`_ | `PROGRAMS`_} <file>... [...])
install(`DIRECTORY`_ <dir>... [...])
install(`SCRIPT`_ <file> [...])
install(`CODE`_ <code> [...])
install(`EXPORT`_ <export-name> [...])
+ install(`RUNTIME_DEPENDENCY_SET`_ <set-name> [...])
Introduction
^^^^^^^^^^^^
@@ -124,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>]
@@ -338,6 +341,49 @@ 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 with an
+ `install(RUNTIME_DEPENDENCY_SET)`_ command.
+
+ This keyword and the ``RUNTIME_DEPENDENCIES`` keyword 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 the following pair
+ of calls:
+
+ .. code-block:: cmake
+
+ install(TARGETS ... RUNTIME_DEPENDENCY_SET <set-name>)
+ install(RUNTIME_DEPENDENCY_SET <set-name> args...)
+
+ where ``<set-name>`` will be a randomly generated set name.
+ The ``args...`` may include any of the following keywords supported by
+ the `install(RUNTIME_DEPENDENCY_SET)`_ command:
+
+ * ``DIRECTORIES``
+ * ``PRE_INCLUDE_REGEXES``
+ * ``PRE_EXCLUDE_REGEXES``
+ * ``POST_INCLUDE_REGEXES``
+ * ``POST_EXCLUDE_REGEXES``
+ * ``POST_INCLUDE_FILES``
+ * ``POST_EXCLUDE_FILES``
+
+ The ``RUNTIME_DEPENDENCIES`` and ``RUNTIME_DEPENDENCY_SET`` keywords 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``,
@@ -382,6 +428,44 @@ 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...
+ [RUNTIME_DEPENDENCY_SET <set-name>]
+ [[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.
+
+The ``RUNTIME_DEPENDENCY_SET`` option causes the runtime artifacts of the
+imported executable, shared library, and module library ``targets`` to be
+added to the ``<set-name>`` runtime dependency set. This set can then be
+installed with an `install(RUNTIME_DEPENDENCY_SET)`_ command.
+
Installing Files
^^^^^^^^^^^^^^^^
@@ -540,7 +624,8 @@ any expression. For example, the code
will extract and install header files from a source tree.
-Some options may follow a ``PATTERN`` or ``REGEX`` expression and are applied
+Some options may follow a ``PATTERN`` or ``REGEX`` expression as described
+under :ref:`string(REGEX) <Regex Specification>` and are applied
only to files or directories matching them. The ``EXCLUDE`` option will
skip the matched file or directory. The ``PERMISSIONS`` option overrides
the permissions setting for the matched file or directory. For
@@ -619,7 +704,8 @@ Custom Installation Logic
.. code-block:: cmake
install([[SCRIPT <file>] [CODE <code>]]
- [COMPONENT <component>] [EXCLUDE_FROM_ALL] [...])
+ [ALL_COMPONENTS | COMPONENT <component>]
+ [EXCLUDE_FROM_ALL] [...])
The ``SCRIPT`` form will invoke the given CMake script files during
installation. If the script file name is a relative path it will be
@@ -634,6 +720,12 @@ example, the code
will print a message during installation.
+.. versionadded:: 3.21
+ When the ``ALL_COMPONENTS`` option is given, the custom installation
+ script code will be executed for every component of a component-specific
+ installation. This option is mutually exclusive with the ``COMPONENT``
+ option.
+
.. versionadded:: 3.14
``<file>`` or ``<code>`` may use "generator expressions" with the syntax
``$<...>`` (in the case of ``<file>``, this refers to their use in the file
@@ -724,7 +816,7 @@ executable from the installation tree using the imported target name
``mp_myexe`` as if the target were built in its own tree.
.. note::
- This command supercedes the :command:`install_targets` command and
+ This command supersedes the :command:`install_targets` command and
the :prop_tgt:`PRE_INSTALL_SCRIPT` and :prop_tgt:`POST_INSTALL_SCRIPT`
target properties. It also replaces the ``FILES`` forms of the
:command:`install_files` and :command:`install_programs` commands.
@@ -733,6 +825,70 @@ 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...]
+ [POST_INCLUDE_FILES files...]
+ [POST_EXCLUDE_FILES files...]
+ [DIRECTORIES directories...]
+ )
+
+Installs a runtime dependency set previously 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.
+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)`_.
+
+The generated install script calls :command:`file(GET_RUNTIME_DEPENDENCIES)`
+on the build-tree files to calculate the runtime dependencies. The build-tree
+executable files are passed as the ``EXECUTABLES`` argument, the build-tree
+shared libraries as the ``LIBRARIES`` argument, and the build-tree modules as
+the ``MODULES`` argument. On macOS, if one of the executables is a
+:prop_tgt:`MACOSX_BUNDLE`, that executable is passed as the
+``BUNDLE_EXECUTABLE`` argument. At most one such bundle executable may be in
+the runtime dependency set on macOS. The :prop_tgt:`MACOSX_BUNDLE` property
+has no effect on other platforms. Note that
+:command:`file(GET_RUNTIME_DEPENDENCIES)` only supports collecting the runtime
+dependencies for Windows, Linux and macOS platforms, so
+``install(RUNTIME_DEPENDENCY_SET)`` has the same limitation.
+
+The following sub-arguments are forwarded through as the corresponding
+arguments to :command:`file(GET_RUNTIME_DEPENDENCIES)` (for those that provide
+a non-empty list of directories, regular expressions or files). They all
+support :manual:`generator expressions <cmake-generator-expressions(7)>`.
+
+* ``DIRECTORIES <directories>``
+* ``PRE_INCLUDE_REGEXES <regexes>``
+* ``PRE_EXCLUDE_REGEXES <regexes>``
+* ``POST_INCLUDE_REGEXES <regexes>``
+* ``POST_EXCLUDE_REGEXES <regexes>``
+* ``POST_INCLUDE_FILES <files>``
+* ``POST_EXCLUDE_FILES <files>``
+
Generated Installation Script
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^