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

Merge topic 'doc-3.21-release'

Browse Source 
24b76eaa93 Help: Improve readability and accuracy of runtime deps-related content
308e5b30c9 Help: Tighten install(SCRIPT) wording for ALL_COMPONENTS option
52dec01729 Help: Add missing versionadded 3.21 for file(RENAME) options

Acked-by: Kitware Robot <kwrobot@kitware.com>
Merge-request: !6302
This commit is contained in:
Craig Scott 2021-07-06 00:02:14 +00:00 committed by Kitware Robot
commit c97823b9b7
2 changed files with 72 additions and 58 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

10
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.
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
@ -703,10 +705,14 @@ Move a file or directory within a filesystem from ``<oldname>`` to
The options are:
``RESULT <result>``
.. versionadded:: 3.21
Set ``<result>`` variable to ``0`` on success or an error message otherwise.
If ``RESULT`` is not specified and the operation fails, an error is emitted.
``NO_REPLACE``
.. versionadded:: 3.21
If the ``<newname>`` path already exists, do not replace it.
If ``RESULT <result>`` is used, the result variable will be
set to ``NO_REPLACE``. Otherwise, an error is emitted.

120
Help/command/install.rst
View File

@ -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 <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
@ -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 ``<set-name>`` runtime dependency set. This set can then be
installed with an `install(RUNTIME_DEPENDENCY_SET)`_ command.
Installing Files
^^^^^^^^^^^^^^^^
@ -693,7 +704,8 @@ Custom Installation Logic
.. code-block:: cmake
install([[SCRIPT <file>] [CODE <code>]]
[COMPONENT <component>] [EXCLUDE_FROM_ALL] [ALL_COMPONENTS] [...])
[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
@ -708,11 +720,11 @@ example, the code
will print a message during installation.
The option ``ALL_COMPONENTS``
.. versionadded:: 3.21
Run the custom installation script code for every component of a
component-specific 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
@ -836,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)`_.
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)`_.
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>``
List of directories to be passed as the ``DIRECTORIES`` argument of
:command:`file(GET_RUNTIME_DEPENDENCIES)`. This argument supports
:manual:`generator expressions <cmake-generator-expressions(7)>`. If a
``DIRECTORIES`` argument evaluates to an empty string, it is not passed to
:command:`file(GET_RUNTIME_DEPENDENCIES)`.
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)>`.
``PRE_INCLUDE_REGEXES <regexes>``, ``PRE_EXCLUDE_REGEXES <regexes>``, ``POST_INCLUDE_REGEXES <regexes>``, ``POST_EXCLUDE_REGEXES <regexes>``
List of regular expressions 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)`.
``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)`.
* ``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
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^