From a5f79b83c79a2445e981dc8856cd91e6925a57ae Mon Sep 17 00:00:00 2001 From: Craig Scott Date: Sat, 2 Mar 2019 21:46:48 +1100 Subject: Help: clarify DESTINATION and TYPE usage for install() --- Help/command/install.rst | 136 +++++++++++++++++++++++++++++------------------ 1 file changed, 85 insertions(+), 51 deletions(-) diff --git a/Help/command/install.rst b/Help/command/install.rst index a0e8c37..6910d6d 100644 --- a/Help/command/install.rst +++ b/Help/command/install.rst @@ -9,11 +9,11 @@ Synopsis .. parsed-literal:: install(`TARGETS`_ ... [...]) - install({`FILES`_ | `PROGRAMS`_} ... [DESTINATION ] [...]) - install(`DIRECTORY`_ ... [DESTINATION ] [...]) + install({`FILES`_ | `PROGRAMS`_} ... [...]) + install(`DIRECTORY`_ ... [...]) install(`SCRIPT`_ [...]) install(`CODE`_ [...]) - install(`EXPORT`_ DESTINATION [...]) + install(`EXPORT`_ [...]) Introduction ^^^^^^^^^^^^ @@ -172,11 +172,20 @@ installation properties apply to all target types. If only one is given then only targets of that type will be installed (which can be used to install just a DLL or just an import library.) -For some target types, the ``DESTINATION`` argument is optional. If no -``DESTINATION`` argument is specified for these target types, the destination -will default to either the appropriate variable from :module:`GNUInstallDirs` -(if it is defined) or a built-in default (if the variable is not defined.) These -defaults are outlined below: +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 +appropriate variable from :module:`GNUInstallDirs`, or set to a built-in +default value if that variable is not defined. The same is true for the +public and private headers associated with the installed targets through the +:prop_tgt:`PUBLIC_HEADER` and :prop_tgt:`PRIVATE_HEADER` target properties. +A destination must always be provided for module libraries, Apple bundles and +frameworks. A destination can be omitted for interface and object libraries, +but they are handled differently (see the discussion of this topic toward the +end of this section). + +The following table shows the target types with their associated variables and +built-in defaults that apply when no destination is given: ================== =============================== ====================== Target Type GNUInstallDirs Variable Built-In Default @@ -188,12 +197,28 @@ defaults are outlined below: ``PUBLIC_HEADER`` ``${CMAKE_INSTALL_INCLUDEDIR}`` ``include`` ================== =============================== ====================== -To make your package compliant with distribution filesystem layout policies, it -is not recommended that you specify a ``DESTINATION`` for a target unless it -must be installed in a nonstandard location. That way, package maintainers can -control the install destination by setting the appropriate cache variables. In -any case, it is recommended that you use the :module:`GNUInstallDirs` variables -in your ``DESTINATION`` arguments whenever possible. +Projects wishing to follow the common practice of installing headers into a +project-specific subdirectory will need to provide a destination rather than +rely on the above. + +To make packages compliant with distribution filesystem layout policies, if +projects must specify a ``DESTINATION``, it is recommended that they use a +path that begins with the appropriate :module:`GNUInstallDirs` variable. +This allows package maintainers to control the install destination by setting +the appropriate cache variables. The following example shows a static library +being installed to the default destination provided by +:module:`GNUInstallDirs`, but with its headers installed to a project-specific +subdirectory that follows the above recommendation: + +.. code-block:: cmake + + add_library(mylib STATIC ...) + set_target_properties(mylib PROPERTIES PUBLIC_HEADER mylib.h) + include(GNUInstallDirs) + install(TARGETS mylib + PUBLIC_HEADER + DESTINATION ${CMAKE_INSTALL_INCLUDEDIR}/myproj + ) In addition to the common options listed above, each target can accept the following additional arguments: @@ -218,11 +243,9 @@ the following additional arguments: install(TARGETS mylib LIBRARY - DESTINATION lib COMPONENT Libraries NAMELINK_COMPONENT Development PUBLIC_HEADER - DESTINATION include COMPONENT Development ) @@ -318,7 +341,7 @@ targets from other directories are up-to-date. You can use to ensure that such out-of-directory targets are built before the subdirectory-specific install rules are run. -The install destination given to the target install ``DESTINATION`` may +An install destination given as a ``DESTINATION`` argument may use "generator expressions" with the syntax ``$<...>``. See the :manual:`cmake-generator-expressions(7)` manual for available expressions. @@ -330,7 +353,8 @@ Installing Files .. code-block:: cmake - install( files... [DESTINATION | TYPE ] + install( files... + TYPE | DESTINATION [PERMISSIONS permissions...] [CONFIGURATIONS [Debug|Release|...]] [COMPONENT ] @@ -354,12 +378,14 @@ The list of ``files...`` given to ``FILES`` or ``PROGRAMS`` may use However, if any item begins in a generator expression it must evaluate to a full path. -Instead of specifying ``DESTINATION``, you may specify a generic file type -via the ``TYPE`` argument as listed below. If a type is selected and no -destination is specified, the destination will default to either the -appropriate variable from :module:`GNUInstallDirs` (if it is defined) or a -built-in default (if the variable is not defined.) These defaults are outlined -below: +Either a ``TYPE`` or a ``DESTINATION`` must be provided, but not both. +A ``TYPE`` argument specifies the generic file type of the files being +installed. A destination will then be set automatically by taking the +corresponding variable from :module:`GNUInstallDirs`, or by using a +built-in default if that variable is not defined. See the table below for +the supported file types and their corresponding variables and built-in +defaults. Projects can provide a ``DESTINATION`` argument instead of a +file type if they wish to explicitly define the install destination. ======================= ================================== ========================= ``TYPE`` Argument GNUInstallDirs Variable Built-In Default @@ -379,7 +405,9 @@ below: ``DOC`` ``${CMAKE_INSTALL_DOCDIR}`` ``/doc`` ======================= ================================== ========================= -It is an error to use ``TYPE`` and ``DESTINATION`` arguments together. +Projects wishing to follow the common practice of installing headers into a +project-specific subdirectory will need to provide a destination rather than +rely on the above. Note that some of the types' built-in defaults use the ``DATAROOT`` directory as a prefix. The ``DATAROOT`` prefix is calculated similarly to the types, with @@ -387,15 +415,21 @@ a prefix. The ``DATAROOT`` prefix is calculated similarly to the types, with default. You cannot use ``DATAROOT`` as a ``TYPE`` parameter; please use ``DATA`` instead. -To make your package compliant with distribution filesystem layout policies, it -is recommended that you specify one of the above generic file types, rather than -a ``DESTINATION`` argument, unless the files must be installed in a nonstandard -location. That way, package maintainers can control the install destination by -setting the appropriate cache variables. In any case, it is recommended that you -use the :module:`GNUInstallDirs` variables in your ``DESTINATION`` arguments -whenever possible. +To make packages compliant with distribution filesystem layout policies, if +projects must specify a ``DESTINATION``, it is recommended that they use a +path that begins with the appropriate :module:`GNUInstallDirs` variable. +This allows package maintainers to control the install destination by setting +the appropriate cache variables. The following example shows how to follow +this advice while installing headers to a project-specific subdirectory: -The install destination given to the files install ``DESTINATION`` may +.. code-block:: cmake + + include(GNUInstallDirs) + install(FILES mylib.h + DESTINATION ${CMAKE_INSTALL_INCLUDEDIR}/myproj + ) + +An install destination given as a ``DESTINATION`` argument may use "generator expressions" with the syntax ``$<...>``. See the :manual:`cmake-generator-expressions(7)` manual for available expressions. @@ -406,7 +440,8 @@ Installing Directories .. code-block:: cmake - install(DIRECTORY dirs... [DESTINATION | TYPE ] + install(DIRECTORY dirs... + TYPE | DESTINATION [FILE_PERMISSIONS permissions...] [DIRECTORY_PERMISSIONS permissions...] [USE_SOURCE_PERMISSIONS] [OPTIONAL] [MESSAGE_NEVER] @@ -477,12 +512,15 @@ will install the ``icons`` directory to ``share/myproj/icons`` and the file permissions, the scripts will be given specific permissions, and any ``CVS`` directories will be excluded. -Instead of specifying ``DESTINATION``, you may specify a generic file type -via the ``TYPE`` argument as listed below. If a type is selected and no -destination is specified, the destination will default to either the -appropriate variable from :module:`GNUInstallDirs` (if it is defined) or a -built-in default (if the variable is not defined.) These defaults are outlined -below: +Either a ``TYPE`` or a ``DESTINATION`` must be provided, but not both. +A ``TYPE`` argument specifies the generic file type of the files within the +listed directories being installed. A destination will then be set +automatically by taking the corresponding variable from +:module:`GNUInstallDirs`, or by using a built-in default if that variable +is not defined. See the table below for the supported file types and their +corresponding variables and built-in defaults. Projects can provide a +``DESTINATION`` argument instead of a file type if they wish to explicitly +define the install destination. ======================= ================================== ========================= ``TYPE`` Argument GNUInstallDirs Variable Built-In Default @@ -502,24 +540,20 @@ below: ``DOC`` ``${CMAKE_INSTALL_DOCDIR}`` ``/doc`` ======================= ================================== ========================= -It is an error to use ``TYPE`` and ``DESTINATION`` arguments together. - Note that some of the types' built-in defaults use the ``DATAROOT`` directory as a prefix. The ``DATAROOT`` prefix is calculated similarly to the types, with ``CMAKE_INSTALL_DATAROOTDIR`` as the variable and ``share`` as the built-in default. You cannot use ``DATAROOT`` as a ``TYPE`` parameter; please use ``DATA`` instead. -To make your package compliant with distribution filesystem layout policies, it -is recommended that you specify one of the above generic file types, rather than -a ``DESTINATION`` argument, unless the files must be installed in a nonstandard -location. That way, package maintainers can control the install destination by -setting the appropriate cache variables. In any case, it is recommended that you -use the :module:`GNUInstallDirs` variables in your ``DESTINATION`` arguments -whenever possible. +To make packages compliant with distribution filesystem layout policies, if +projects must specify a ``DESTINATION``, it is recommended that they use a +path that begins with the appropriate :module:`GNUInstallDirs` variable. +This allows package maintainers to control the install destination by setting +the appropriate cache variables. -The list of ``dirs...`` given to ``DIRECTORY`` and the install destination -given to the directory install ``DESTINATION`` may use "generator expressions" +The list of ``dirs...`` given to ``DIRECTORY`` and an install destination +given as a ``DESTINATION`` argument may use "generator expressions" with the syntax ``$<...>``. See the :manual:`cmake-generator-expressions(7)` manual for available expressions. -- cgit v0.12