From 72f2448e82d8b3e90fa733cb6c631298083ae06b Mon Sep 17 00:00:00 2001 From: Kyle Edwards Date: Wed, 19 May 2021 15:19:38 -0400 Subject: Help: Add documentation for runtime dependency installation --- Help/command/install.rst | 108 ++++++++++++++++++++++ Help/manual/cmake-generator-expressions.7.rst | 5 +- Help/release/dev/install-runtime-dependencies.rst | 9 ++ 3 files changed, 120 insertions(+), 2 deletions(-) create mode 100644 Help/release/dev/install-runtime-dependencies.rst 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`_ [...]) install(`CODE`_ [...]) install(`EXPORT`_ [...]) + install(`RUNTIME_DEPENDENCY_SET`_ [...]) Introduction ^^^^^^^^^^^^ @@ -125,6 +126,7 @@ Installing Targets .. code-block:: cmake install(TARGETS targets... [EXPORT ] + [RUNTIME_DEPENDENCIES args...|RUNTIME_DEPENDENCY_SET ] [[ARCHIVE|LIBRARY|RUNTIME|OBJECTS|FRAMEWORK|BUNDLE| PRIVATE_HEADER|PUBLIC_HEADER|RESOURCE] [DESTINATION ] @@ -339,6 +341,34 @@ top level: relative path is specified, it is treated as relative to the ``$``. +``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 ] [[LIBRARY|RUNTIME|FRAMEWORK|BUNDLE] [DESTINATION ] [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 + [[LIBRARY|RUNTIME|FRAMEWORK] + [DESTINATION ] + [PERMISSIONS permissions...] + [CONFIGURATIONS [Debug|Release|...]] + [COMPONENT ] + [NAMELINK_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 `` + List of directories to be passed as the ``DIRECTORIES`` argument of + :command:`file(GET_RUNTIME_DEPENDENCIES)`. This argument supports + :manual:`generator expressions `. If a + ``DIRECTORIES`` argument evaluates to an empty string, it is not passed to + :command:`file(GET_RUNTIME_DEPENDENCIES)`. + +``PRE_INCLUDE_REGEXES ``, ``PRE_EXCLUDE_REGEXES ``, ``POST_INCLUDE_REGEXES ``, ``POST_EXCLUDE_REGEXES `` + List of regular expressions to be passed as their respective arguments to + :command:`file(GET_RUNTIME_DEPENDENCIES)`. These arguments support + :manual:`generator expressions `. If an + argument evaluates to an empty string, it is not passed to + :command:`file(GET_RUNTIME_DEPENDENCIES)`. + +``POST_INCLUDE_FILES ``, ``POST_EXCLUDE_FILES `` + List of files to be passed as their respective arguments to + :command:`file(GET_RUNTIME_DEPENDENCIES)`. These arguments support + :manual:`generator expressions `. 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:: $ 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)`. -- cgit v0.12