echo/CMake
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Help: Improve readability and accuracy of runtime deps-related content

Browse Source 
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).
This commit is contained in:
Craig Scott 2021-07-03 19:00:14 +10:00
parent 308e5b30c9
commit 24b76eaa93
2 changed files with 61 additions and 52 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

6
Help/command/file.rst
View File

@ -189,8 +189,10 @@ the ``<format>`` and ``UTC`` options.
Recursively get the list of libraries depended on by the given files. 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. 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)` It is intended for use at install time, either from code generated by the
block. For example: :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 .. code-block:: cmake

107
Help/command/install.rst
View File

@ -346,10 +346,10 @@ top level:
This option causes all runtime dependencies of installed executable, shared This option causes all runtime dependencies of installed executable, shared
library, and module targets to be added to the specified runtime dependency 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. `install(RUNTIME_DEPENDENCY_SET)`_ command.
This argument and the ``RUNTIME_DEPENDENCIES`` argument are mutually This keyword and the ``RUNTIME_DEPENDENCIES`` keyword are mutually
exclusive. exclusive.
``RUNTIME_DEPENDENCIES`` ``RUNTIME_DEPENDENCIES``
@ -361,13 +361,28 @@ top level:
arguments are used to determine the properties (``DESTINATION``, arguments are used to determine the properties (``DESTINATION``,
``COMPONENT``, etc.) of the installation of these dependencies. ``COMPONENT``, etc.) of the installation of these dependencies.
``RUNTIME_DEPENDENCIES`` is semantically equivalent to calling ``RUNTIME_DEPENDENCIES`` is semantically equivalent to the following pair
``install(TARGETS ... RUNTIME_DEPENDENCY_SET)`` and then of calls:
`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 .. code-block:: cmake
exclusive.
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 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 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 :prop_tgt:`MACOSX_BUNDLE` executables, and :prop_tgt:`BUNDLE` CFBundles, the
entire directory is installed. entire directory is installed.
``IMPORTED_RUNTIME_ARTIFACTS`` accepts the following additional arguments: The ``RUNTIME_DEPENDENCY_SET`` option causes the runtime artifacts of the
imported executable, shared library, and module library ``targets`` to be
``RUNTIME_DEPENDENCY_SET`` added to the ``<set-name>`` runtime dependency set. This set can then be
installed with an `install(RUNTIME_DEPENDENCY_SET)`_ command.
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 Installing Files
^^^^^^^^^^^^^^^^ ^^^^^^^^^^^^^^^^
@ -837,50 +848,46 @@ Installing Runtime Dependencies
[PRE_EXCLUDE_REGEXES regexes...] [PRE_EXCLUDE_REGEXES regexes...]
[POST_INCLUDE_REGEXES regexes...] [POST_INCLUDE_REGEXES regexes...]
[POST_EXCLUDE_REGEXES regexes...] [POST_EXCLUDE_REGEXES regexes...]
[POST_INCLUDE_FILES files...]
[POST_EXCLUDE_FILES files...]
[DIRECTORIES directories...] [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 `install(TARGETS)`_ or `install(IMPORTED_RUNTIME_ARTIFACTS)`_ commands. The
dependencies of targets belonging to a runtime dependency set are installed in dependencies of targets belonging to a runtime dependency set are installed in
the ``RUNTIME`` destination and component on DLL platforms, and in the the ``RUNTIME`` destination and component on DLL platforms, and in the
``LIBRARY`` destination and component on non-DLL platforms. macOS frameworks ``LIBRARY`` destination and component on non-DLL platforms. macOS frameworks
are installed in the ``FRAMEWORK`` destination and component. The generated are installed in the ``FRAMEWORK`` destination and component.
install script calls :command:`file(GET_RUNTIME_DEPENDENCIES)` on the Targets built within the build tree will never be installed as runtime
build-tree files to calculate the runtime dependencies, with the build-tree dependencies, nor will their own dependencies, unless the targets themselves
executable files as the ``EXECUTABLES`` argument, the build-tree shared are installed with `install(TARGETS)`_.
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: 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.
``DIRECTORIES <directories>`` The following sub-arguments are forwarded through as the corresponding
List of directories to be passed as the ``DIRECTORIES`` argument of arguments to :command:`file(GET_RUNTIME_DEPENDENCIES)` (for those that provide
:command:`file(GET_RUNTIME_DEPENDENCIES)`. This argument supports a non-empty list of directories, regular expressions or files). They all
:manual:`generator expressions <cmake-generator-expressions(7)>`. If a support :manual:`generator expressions <cmake-generator-expressions(7)>`.
``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>`` * ``DIRECTORIES <directories>``
List of regular expressions to be passed as their respective arguments to * ``PRE_INCLUDE_REGEXES <regexes>``
:command:`file(GET_RUNTIME_DEPENDENCIES)`. These arguments support * ``PRE_EXCLUDE_REGEXES <regexes>``
:manual:`generator expressions <cmake-generator-expressions(7)>`. If an * ``POST_INCLUDE_REGEXES <regexes>``
argument evaluates to an empty string, it is not passed to * ``POST_EXCLUDE_REGEXES <regexes>``
:command:`file(GET_RUNTIME_DEPENDENCIES)`. * ``POST_INCLUDE_FILES <files>``
* ``POST_EXCLUDE_FILES <files>``
``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 Generated Installation Script
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^