From 24b76eaa93447d3521b55c5233036ce3ca752d6b Mon Sep 17 00:00:00 2001 From: Craig Scott Date: Sat, 3 Jul 2021 19:00:14 +1000 Subject: Help: Improve readability and accuracy of runtime deps-related content Duplicated textual patterns are factored out to make the text more readable. The POST_INCLUDE_FILES and POST_EXCLUDE_FILES were also previously missing from the main syntax block for install(RUNTIME_DEPENDENCY_SET). --- Help/command/file.rst | 6 ++- Help/command/install.rst | 113 +++++++++++++++++++++++++---------------------- 2 files changed, 64 insertions(+), 55 deletions(-) diff --git a/Help/command/file.rst b/Help/command/file.rst index 8ce27ff092..943bf7c1b8 100644 --- a/Help/command/file.rst +++ b/Help/command/file.rst @@ -189,8 +189,10 @@ the ```` and ``UTC`` options. Recursively get the list of libraries depended on by the given files. Please note that this sub-command is not intended to be used in project mode. -Instead, use it in an :command:`install(CODE)` or :command:`install(SCRIPT)` -block. For example: +It is intended for use at install time, either from code generated by the +:command:`install(RUNTIME_DEPENDENCY_SET)` command, or from code provided by +the project via :command:`install(CODE)` or :command:`install(SCRIPT)`. +For example: .. code-block:: cmake diff --git a/Help/command/install.rst b/Help/command/install.rst index ace53b3f90..c6af4897e0 100644 --- a/Help/command/install.rst +++ b/Help/command/install.rst @@ -346,10 +346,10 @@ top level: 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 + set. This set can then be installed with an `install(RUNTIME_DEPENDENCY_SET)`_ command. - This argument and the ``RUNTIME_DEPENDENCIES`` argument are mutually + This keyword and the ``RUNTIME_DEPENDENCIES`` keyword are mutually exclusive. ``RUNTIME_DEPENDENCIES`` @@ -361,13 +361,28 @@ top level: 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)`_. + ``RUNTIME_DEPENDENCIES`` is semantically equivalent to the following pair + of calls: - This argument and the ``RUNTIME_DEPENDENCY_SET`` argument are mutually - exclusive. + .. code-block:: cmake + + install(TARGETS ... RUNTIME_DEPENDENCY_SET ) + install(RUNTIME_DEPENDENCY_SET args...) + + where ```` 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 @@ -446,14 +461,10 @@ 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. +The ``RUNTIME_DEPENDENCY_SET`` option causes the runtime artifacts of the +imported executable, shared library, and module library ``targets`` to be +added to the ```` runtime dependency set. This set can then be +installed with an `install(RUNTIME_DEPENDENCY_SET)`_ command. Installing Files ^^^^^^^^^^^^^^^^ @@ -837,50 +848,46 @@ Installing Runtime Dependencies [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 created by one or more +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. 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)`. +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 `. + +* ``DIRECTORIES `` +* ``PRE_INCLUDE_REGEXES `` +* ``PRE_EXCLUDE_REGEXES `` +* ``POST_INCLUDE_REGEXES `` +* ``POST_EXCLUDE_REGEXES `` +* ``POST_INCLUDE_FILES `` +* ``POST_EXCLUDE_FILES `` Generated Installation Script ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -- cgit v1.2.1