From 5d15231a672361b784073384df40b33c40943453 Mon Sep 17 00:00:00 2001 From: Brad King Date: Wed, 2 Aug 2023 14:39:43 -0400 Subject: Help: Revert "improve install() documentation of argument ordering" Revert commit f09fda97d8 (Help: improve install() documentation of argument ordering, 2018-01-08, v3.11.0-rc1~126^2). Although the example it added is correct, its explanation is misleading. Revert it to make room for an alternative. Issue: #25144 Issue: #16362 --- Help/command/install.rst | 16 +--------------- 1 file changed, 1 insertion(+), 15 deletions(-) diff --git a/Help/command/install.rst b/Help/command/install.rst index b7a49e6..541536d 100644 --- a/Help/command/install.rst +++ b/Help/command/install.rst @@ -67,21 +67,7 @@ signatures that specify them. The common options are: ``CONFIGURATIONS`` Specify a list of build configurations for which the install rule - applies (Debug, Release, etc.). Note that the values specified for - this option only apply to options listed AFTER the ``CONFIGURATIONS`` - option. For example, to set separate install paths for the Debug and - Release configurations, do the following: - - .. code-block:: cmake - - install(TARGETS target - CONFIGURATIONS Debug - RUNTIME DESTINATION Debug/bin) - install(TARGETS target - CONFIGURATIONS Release - RUNTIME DESTINATION Release/bin) - - Note that ``CONFIGURATIONS`` appears BEFORE ``RUNTIME DESTINATION``. + applies (Debug, Release, etc.). ``COMPONENT`` Specify an installation component name with which the install rule -- cgit v0.12 From ae381e10750709ee416d8efa640b506364ad5b4f Mon Sep 17 00:00:00 2001 From: Brad King Date: Thu, 3 Aug 2023 10:40:59 -0400 Subject: Help: Reorganize install() sections After switching to the signature directive we no longer need per-signature sections. Group all the signatures in one section. Add a table of contents since it is no longer redundant with the synopsis. --- Help/command/install.rst | 26 ++++++-------------------- 1 file changed, 6 insertions(+), 20 deletions(-) diff --git a/Help/command/install.rst b/Help/command/install.rst index 541536d..4494385 100644 --- a/Help/command/install.rst +++ b/Help/command/install.rst @@ -1,6 +1,10 @@ install ------- +.. only:: html + + .. contents:: + Specify rules to run at install time. Synopsis @@ -107,8 +111,8 @@ signatures that specify them. The common options are: they will be created according to the uname rules on Unix-like platforms. Windows platforms are unaffected. -Installing Targets -^^^^^^^^^^^^^^^^^^ +Signatures +^^^^^^^^^^ .. signature:: install(TARGETS ... [...]) @@ -475,9 +479,6 @@ Installing Targets to ensure that such out-of-directory targets are built before the subdirectory-specific install rules are run. -Installing Imported Runtime Artifacts -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - .. signature:: install(IMPORTED_RUNTIME_ARTIFACTS ... [...]) @@ -515,9 +516,6 @@ Installing Imported Runtime Artifacts added to the ```` runtime dependency set. This set can then be installed with an :command:`install(RUNTIME_DEPENDENCY_SET)` command. -Installing Files -^^^^^^^^^^^^^^^^ - .. signature:: install(FILES ... [...]) install(PROGRAMS ... [...]) @@ -620,9 +618,6 @@ Installing Files use "generator expressions" with the syntax ``$<...>``. See the :manual:`cmake-generator-expressions(7)` manual for available expressions. -Installing Directories -^^^^^^^^^^^^^^^^^^^^^^ - .. signature:: install(DIRECTORY ... [...]) @@ -760,9 +755,6 @@ Installing Directories The list of ``dirs...`` given to ``DIRECTORY`` may use "generator expressions" too. -Custom Installation Logic -^^^^^^^^^^^^^^^^^^^^^^^^^ - .. signature:: install(SCRIPT [...]) install(CODE [...]) @@ -800,9 +792,6 @@ Custom Installation Logic name, not the file's contents). See the :manual:`cmake-generator-expressions(7)` manual for available expressions. -Installing Exports -^^^^^^^^^^^^^^^^^^ - .. signature:: install(EXPORT [...]) @@ -910,9 +899,6 @@ Installing Exports :command:`install_files`, and :command:`install_programs` commands is not defined. -Installing Runtime Dependencies -^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ - .. signature:: install(RUNTIME_DEPENDENCY_SET [...]) -- cgit v0.12 From 7bd6478dd06b73b32a8a0d72883eceb912f91176 Mon Sep 17 00:00:00 2001 From: Brad King Date: Wed, 2 Aug 2023 14:43:23 -0400 Subject: Help: Use argument value placeholders consistently in install(TARGETS) --- Help/command/install.rst | 91 ++++++++++++++++++++++++------------------------ 1 file changed, 46 insertions(+), 45 deletions(-) diff --git a/Help/command/install.rst b/Help/command/install.rst index 4494385..12aa906 100644 --- a/Help/command/install.rst +++ b/Help/command/install.rst @@ -43,7 +43,7 @@ installation options for files and targets. Options common to multiple signatures are covered here but they are valid only for signatures that specify them. The common options are: -``DESTINATION`` +``DESTINATION `` Specify the directory on disk to which a file will be installed. Arguments can be relative or absolute paths. @@ -62,18 +62,18 @@ signatures that specify them. The common options are: :variable:`CMAKE_INSTALL_PREFIX`; this prefix is used by default if the DESTINATION is a relative path. -``PERMISSIONS`` +``PERMISSIONS ...`` Specify permissions for installed files. Valid permissions are ``OWNER_READ``, ``OWNER_WRITE``, ``OWNER_EXECUTE``, ``GROUP_READ``, ``GROUP_WRITE``, ``GROUP_EXECUTE``, ``WORLD_READ``, ``WORLD_WRITE``, ``WORLD_EXECUTE``, ``SETUID``, and ``SETGID``. Permissions that do not make sense on certain platforms are ignored on those platforms. -``CONFIGURATIONS`` +``CONFIGURATIONS ...`` Specify a list of build configurations for which the install rule applies (Debug, Release, etc.). -``COMPONENT`` +``COMPONENT `` Specify an installation component name with which the install rule is associated, such as ``Runtime`` or ``Development``. During component-specific installation only install rules associated with @@ -89,7 +89,7 @@ signatures that specify them. The common options are: Specify that the file is excluded from a full installation and only installed as part of a component-specific installation -``RENAME`` +``RENAME `` Specify a name for an installed file that may be different from the original file. Renaming is allowed only when a single file is installed by the command. @@ -121,13 +121,14 @@ Signatures .. code-block:: cmake - install(TARGETS targets... [EXPORT ] - [RUNTIME_DEPENDENCIES args...|RUNTIME_DEPENDENCY_SET ] + install(TARGETS ... [EXPORT ] + [RUNTIME_DEPENDENCIES ...|RUNTIME_DEPENDENCY_SET ] [[ARCHIVE|LIBRARY|RUNTIME|OBJECTS|FRAMEWORK|BUNDLE| - PRIVATE_HEADER|PUBLIC_HEADER|RESOURCE|FILE_SET |CXX_MODULES_BMI] + PRIVATE_HEADER|PUBLIC_HEADER|RESOURCE| + FILE_SET |CXX_MODULES_BMI] [DESTINATION ] - [PERMISSIONS permissions...] - [CONFIGURATIONS [Debug|Release|...]] + [PERMISSIONS ...] + [CONFIGURATIONS ...] [COMPONENT ] [NAMELINK_COMPONENT ] [OPTIONAL] [EXCLUDE_FROM_ALL] @@ -199,12 +200,12 @@ Signatures Similar to ``PUBLIC_HEADER`` and ``PRIVATE_HEADER``, but for ``RESOURCE`` files. See :prop_tgt:`RESOURCE` for details. - ``FILE_SET `` + ``FILE_SET `` .. versionadded:: 3.23 File sets are defined by the :command:`target_sources(FILE_SET)` command. - If the file set ```` exists and is ``PUBLIC`` or ``INTERFACE``, any - files in the set are installed under the destination (see below). + If the file set ```` exists and is ``PUBLIC`` or ``INTERFACE``, + any files in the set are installed under the destination (see below). The directory structure relative to the file set's base directories is preserved. For example, a file added to the file set as ``/blah/include/myproj/here.h`` with a base directory ``/blah/include`` @@ -392,7 +393,7 @@ Signatures If a relative path is specified, it is treated as relative to the :genex:`$`. - ``RUNTIME_DEPENDENCY_SET`` + ``RUNTIME_DEPENDENCY_SET `` .. versionadded:: 3.21 This option causes all runtime dependencies of installed executable, shared @@ -403,7 +404,7 @@ Signatures This keyword and the ``RUNTIME_DEPENDENCIES`` keyword are mutually exclusive. - ``RUNTIME_DEPENDENCIES`` + ``RUNTIME_DEPENDENCIES ...`` .. versionadded:: 3.21 This option causes all runtime dependencies of installed executable, shared @@ -418,10 +419,10 @@ Signatures .. code-block:: cmake install(TARGETS ... RUNTIME_DEPENDENCY_SET ) - install(RUNTIME_DEPENDENCY_SET args...) + install(RUNTIME_DEPENDENCY_SET ...) where ```` will be a randomly generated set name. - The ``args...`` may include any of the following keywords supported by + ``...`` may include any of the following keywords supported by the :command:`install(RUNTIME_DEPENDENCY_SET)` command: * ``DIRECTORIES`` @@ -488,12 +489,12 @@ Signatures .. code-block:: cmake - install(IMPORTED_RUNTIME_ARTIFACTS targets... + install(IMPORTED_RUNTIME_ARTIFACTS ... [RUNTIME_DEPENDENCY_SET ] [[LIBRARY|RUNTIME|FRAMEWORK|BUNDLE] [DESTINATION ] - [PERMISSIONS permissions...] - [CONFIGURATIONS [Debug|Release|...]] + [PERMISSIONS ...] + [CONFIGURATIONS ...] [COMPONENT ] [OPTIONAL] [EXCLUDE_FROM_ALL] ] [...] @@ -530,10 +531,10 @@ Signatures .. code-block:: cmake - install( files... + install( ... TYPE | DESTINATION - [PERMISSIONS permissions...] - [CONFIGURATIONS [Debug|Release|...]] + [PERMISSIONS ...] + [CONFIGURATIONS ...] [COMPONENT ] [RENAME ] [OPTIONAL] [EXCLUDE_FROM_ALL]) @@ -634,14 +635,14 @@ Signatures install(DIRECTORY dirs... TYPE | DESTINATION - [FILE_PERMISSIONS permissions...] - [DIRECTORY_PERMISSIONS permissions...] + [FILE_PERMISSIONS ...] + [DIRECTORY_PERMISSIONS ...] [USE_SOURCE_PERMISSIONS] [OPTIONAL] [MESSAGE_NEVER] - [CONFIGURATIONS [Debug|Release|...]] + [CONFIGURATIONS ...] [COMPONENT ] [EXCLUDE_FROM_ALL] [FILES_MATCHING] [[PATTERN | REGEX ] - [EXCLUDE] [PERMISSIONS permissions...]] [...]) + [EXCLUDE] [PERMISSIONS ...]] [...]) The ``DIRECTORY`` form installs contents of one or more directories to a given destination. The directory structure is copied verbatim to the @@ -801,8 +802,8 @@ Signatures install(EXPORT DESTINATION [NAMESPACE ] [FILE .cmake] - [PERMISSIONS permissions...] - [CONFIGURATIONS [Debug|Release|...] + [PERMISSIONS ...] + [CONFIGURATIONS ...] [CXX_MODULES_DIRECTORY ] [EXPORT_LINK_INTERFACE_LIBRARIES] [COMPONENT ] @@ -911,19 +912,19 @@ Signatures install(RUNTIME_DEPENDENCY_SET [[LIBRARY|RUNTIME|FRAMEWORK] [DESTINATION ] - [PERMISSIONS permissions...] - [CONFIGURATIONS [Debug|Release|...]] + [PERMISSIONS ...] + [CONFIGURATIONS ...] [COMPONENT ] [NAMELINK_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...] + [PRE_INCLUDE_REGEXES ...] + [PRE_EXCLUDE_REGEXES ...] + [POST_INCLUDE_REGEXES ...] + [POST_EXCLUDE_REGEXES ...] + [POST_INCLUDE_FILES ...] + [POST_EXCLUDE_FILES ...] + [DIRECTORIES ...] ) Installs a runtime dependency set previously created by one or more @@ -954,13 +955,13 @@ Signatures 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 `` + * ``DIRECTORIES ...`` + * ``PRE_INCLUDE_REGEXES ...`` + * ``PRE_EXCLUDE_REGEXES ...`` + * ``POST_INCLUDE_REGEXES ...`` + * ``POST_EXCLUDE_REGEXES ...`` + * ``POST_INCLUDE_FILES ...`` + * ``POST_EXCLUDE_FILES ...`` Generated Installation Script ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -- cgit v0.12 From 0827305032234e651144e8b7051568a21bb090ef Mon Sep 17 00:00:00 2001 From: Brad King Date: Wed, 2 Aug 2023 14:53:07 -0400 Subject: Help: Clarify install(TARGETS) artifact-kind option group ordering Revise the signature and description to explicitly distinguish the initial group of artifact options from later groups that apply to a specific kind. Issue: #25144 Fixes: #16362 --- Help/command/install.rst | 54 +++++++++++++++++++++++++++++++----------------- 1 file changed, 35 insertions(+), 19 deletions(-) diff --git a/Help/command/install.rst b/Help/command/install.rst index 12aa906..899afea 100644 --- a/Help/command/install.rst +++ b/Help/command/install.rst @@ -38,6 +38,8 @@ are executed in order during installation. The environment variable :envvar:`CMAKE_INSTALL_MODE` can override the default copying behavior of ``install()``. +.. _`common options`: + There are multiple signatures for this command. Some of them define installation options for files and targets. Options common to multiple signatures are covered here but they are valid only for @@ -69,10 +71,20 @@ signatures that specify them. The common options are: ``WORLD_EXECUTE``, ``SETUID``, and ``SETGID``. Permissions that do not make sense on certain platforms are ignored on those platforms. + If this option is used multiple times in a single call, its list + of permissions accumulates. If an :command:`install(TARGETS)` call + uses `\`_ arguments, a separate list of permissions + is accumulated for each kind of artifact. + ``CONFIGURATIONS ...`` Specify a list of build configurations for which the install rule applies (Debug, Release, etc.). + If this option is used multiple times in a single call, its list + of configurations accumulates. If an :command:`install(TARGETS)` + call uses `\`_ arguments, a separate list of + configurations is accumulated for each kind of artifact. + ``COMPONENT `` Specify an installation component name with which the install rule is associated, such as ``Runtime`` or ``Development``. During @@ -123,23 +135,31 @@ Signatures install(TARGETS ... [EXPORT ] [RUNTIME_DEPENDENCIES ...|RUNTIME_DEPENDENCY_SET ] - [[ARCHIVE|LIBRARY|RUNTIME|OBJECTS|FRAMEWORK|BUNDLE| - PRIVATE_HEADER|PUBLIC_HEADER|RESOURCE| - FILE_SET |CXX_MODULES_BMI] - [DESTINATION ] - [PERMISSIONS ...] - [CONFIGURATIONS ...] - [COMPONENT ] - [NAMELINK_COMPONENT ] - [OPTIONAL] [EXCLUDE_FROM_ALL] - [NAMELINK_ONLY|NAMELINK_SKIP] - ] [...] + [...] + [ ...]... [INCLUDES DESTINATION [ ...]] ) - The ``TARGETS`` form specifies rules for installing targets from a - project. There are several kinds of target :ref:`Output Artifacts` - that may be installed: + where ``...`` group may contain: + + .. code-block:: cmake + + [DESTINATION ] + [PERMISSIONS ...] + [CONFIGURATIONS ...] + [COMPONENT ] + [NAMELINK_COMPONENT ] + [OPTIONAL] [EXCLUDE_FROM_ALL] + [NAMELINK_ONLY|NAMELINK_SKIP] + + The first ``...`` group applies to target + :ref:`Output Artifacts` that do not have a dedicated group specified + later in the same call. + + .. _``: + + Each `` ...`` group applies to + :ref:`Output Artifacts` of the specified artifact kind: ``ARCHIVE`` Target artifacts of this kind include: @@ -223,10 +243,6 @@ Signatures derived from the names of the modules. An empty ``DESTINATION`` may be used to suppress installing these files (for use in generic code). - For each of these arguments given, the arguments following them only apply - to the target or file type specified in the argument. If none is given, the - installation properties apply to all target types. - For regular executables, static libraries and shared libraries, the ``DESTINATION`` argument is not required. For these target types, when ``DESTINATION`` is omitted, a default destination will be taken from the @@ -285,7 +301,7 @@ Signatures DESTINATION ${CMAKE_INSTALL_INCLUDEDIR}/myproj ) - In addition to the common options listed above, each target can accept + In addition to the `common options`_ listed above, each target can accept the following additional arguments: ``NAMELINK_COMPONENT`` -- cgit v0.12 From b97350a151247d07943f46f1a46e57a0ecd0fb9c Mon Sep 17 00:00:00 2001 From: Brad King Date: Thu, 3 Aug 2023 10:44:18 -0400 Subject: Help: Add more install(TARGETS) examples Add examples showing per-artifact components and per-configuration destinations. Fixes: #25144 --- Help/command/install.rst | 132 +++++++++++++++++++++++++++++++++-------------- 1 file changed, 94 insertions(+), 38 deletions(-) diff --git a/Help/command/install.rst b/Help/command/install.rst index 899afea..4de3ce1 100644 --- a/Help/command/install.rst +++ b/Help/command/install.rst @@ -325,24 +325,8 @@ Signatures the linker import file created, on macOS, for shared libraries with :prop_tgt:`ENABLE_EXPORTS` enabled. - Consider the following example: - - .. code-block:: cmake - - install(TARGETS mylib - LIBRARY - COMPONENT Libraries - NAMELINK_COMPONENT Development - PUBLIC_HEADER - COMPONENT Development - ) - - In this scenario, if you choose to install only the ``Development`` - component, both the headers and namelink will be installed without the - library. (If you don't also install the ``Libraries`` component, the - namelink will be a dangling symlink, and projects that link to the library - will have build errors.) If you install only the ``Libraries`` component, - only the library will be installed, without the headers and namelink. + See the `Example: Install Targets with Per-Artifact Components`_ + for an example using ``NAMELINK_COMPONENT``. This option is typically used for package managers that have separate runtime and development packages. For example, on Debian systems, the @@ -452,26 +436,6 @@ Signatures 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``, - ``mySharedLib``, and ``myStaticLib``. The code: - - .. code-block:: cmake - - install(TARGETS myExe mySharedLib myStaticLib - RUNTIME DESTINATION bin - LIBRARY DESTINATION lib - ARCHIVE DESTINATION lib/static) - install(TARGETS mySharedLib DESTINATION /some/full/path) - - will install ``myExe`` to ``/bin`` and ``myStaticLib`` to - ``/lib/static``. On non-DLL platforms ``mySharedLib`` will be - installed to ``/lib`` and ``/some/full/path``. On DLL platforms - the ``mySharedLib`` DLL will be installed to ``/bin`` and - ``/some/full/path`` and its import library will be installed to - ``/lib/static`` and ``/some/full/path``. - :ref:`Interface Libraries` may be listed among the targets to install. They install no artifacts but will be included in an associated ``EXPORT``. If :ref:`Object Libraries` are listed but given no destination for their @@ -979,6 +943,98 @@ Signatures * ``POST_INCLUDE_FILES ...`` * ``POST_EXCLUDE_FILES ...`` +Examples +^^^^^^^^ + +Example: Install Targets with Per-Artifact Components +""""""""""""""""""""""""""""""""""""""""""""""""""""" + +Consider a project that defines targets with different artifact kinds: + +.. code-block:: cmake + + add_executable(myExe myExe.c) + add_library(myStaticLib STATIC myStaticLib.c) + target_sources(myStaticLib PUBLIC FILE_SET HEADERS FILES myStaticLib.h) + add_library(mySharedLib SHARED mySharedLib.c) + target_sources(mySharedLib PUBLIC FILE_SET HEADERS FILES mySharedLib.h) + set_property(TARGET mySharedLib PROPERTY SOVERSION 1) + +We may call :command:`install(TARGETS)` with `\`_ arguments +to specify different options for each kind of artifact: + +.. code-block:: cmake + + install(TARGETS + myExe + mySharedLib + myStaticLib + RUNTIME # Following options apply to runtime artifacts. + COMPONENT Runtime + LIBRARY # Following options apply to library artifacts. + COMPONENT Runtime + NAMELINK_COMPONENT Development + ARCHIVE # Following options apply to archive artifacts. + COMPONENT Development + DESTINATION lib/static + FILE_SET HEADERS # Following options apply to file set HEADERS. + COMPONENT Development + ) + +This will: + +* Install ``myExe`` to ``/bin``, the default RUNTIME artifact + destination, as part of the ``Runtime`` component. + +* On non-DLL platforms: + + * Install ``libmySharedLib.so.1`` to ``/lib``, the default + LIBRARY artifact destination, as part of the ``Runtime`` component. + + * Install the ``libmySharedLib.so`` "namelink" (symbolic link) to + ``/lib``, the default LIBRARY artifact destination, as part + of the ``Development`` component. + +* On DLL platforms: + + * Install ``mySharedLib.dll`` to ``/bin``, the default RUNTIME + artifact destination, as part of the ``Runtime`` component. + + * Install ``mySharedLib.lib`` to ``/lib/static``, the specified + ARCHIVE artifact destination, as part of the ``Development`` component. + +* Install ``myStaticLib`` to ``/lib/static``, the specified + ARCHIVE artifact destination, as part of the ``Development`` component. + +* Install ``mySharedLib.h`` and ``myStaticLib.h`` to ``/include``, + the default destination for a file set of type HEADERS, as part of the + ``Development`` component. + +Example: Install Targets to Per-Config Destinations +""""""""""""""""""""""""""""""""""""""""""""""""""" + +Each :command:`install(TARGETS)` call installs a given target +:ref:`output artifact ` to at most one ``DESTINATION``, +but the install rule itself may be filtered by the ``CONFIGURATIONS`` option. +In order to install to a different destination for each configuration, one +call per configuration is needed. For example, the code: + +.. code-block:: cmake + + install(TARGETS myExe + CONFIGURATIONS Debug + RUNTIME + DESTINATION Debug/bin + ) + install(TARGETS myExe + CONFIGURATIONS Release + RUNTIME + DESTINATION Release/bin + ) + +will install ``myExe`` to ``/Debug/bin`` in the Debug configuration, +and to ``/Release/bin`` in the Release configuration. + Generated Installation Script ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -- cgit v0.12