Commit ec79045b authored by Brad King's avatar Brad King
Browse files

Merge branch 'docs-install-destinations' into release-3.14

Merge-request: !3052
parents 216fff28 a5f79b83
...@@ -9,11 +9,11 @@ Synopsis ...@@ -9,11 +9,11 @@ Synopsis
.. parsed-literal:: .. parsed-literal::
install(`TARGETS`_ <target>... [...]) install(`TARGETS`_ <target>... [...])
install({`FILES`_ | `PROGRAMS`_} <file>... [DESTINATION <dir>] [...]) install({`FILES`_ | `PROGRAMS`_} <file>... [...])
install(`DIRECTORY`_ <dir>... [DESTINATION <dir>] [...]) install(`DIRECTORY`_ <dir>... [...])
install(`SCRIPT`_ <file> [...]) install(`SCRIPT`_ <file> [...])
install(`CODE`_ <code> [...]) install(`CODE`_ <code> [...])
install(`EXPORT`_ <export-name> DESTINATION <dir> [...]) install(`EXPORT`_ <export-name> [...])
Introduction Introduction
^^^^^^^^^^^^ ^^^^^^^^^^^^
...@@ -172,11 +172,20 @@ installation properties apply to all target types. If only one is given then ...@@ -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 only targets of that type will be installed (which can be used to install
just a DLL or just an import library.) just a DLL or just an import library.)
For some target types, the ``DESTINATION`` argument is optional. If no For regular executables, static libraries and shared libraries, the
``DESTINATION`` argument is specified for these target types, the destination ``DESTINATION`` argument is not required. For these target types, when
will default to either the appropriate variable from :module:`GNUInstallDirs` ``DESTINATION`` is omitted, a default destination will be taken from the
(if it is defined) or a built-in default (if the variable is not defined.) These appropriate variable from :module:`GNUInstallDirs`, or set to a built-in
defaults are outlined below: 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 Target Type GNUInstallDirs Variable Built-In Default
...@@ -188,12 +197,28 @@ defaults are outlined below: ...@@ -188,12 +197,28 @@ defaults are outlined below:
``PUBLIC_HEADER`` ``${CMAKE_INSTALL_INCLUDEDIR}`` ``include`` ``PUBLIC_HEADER`` ``${CMAKE_INSTALL_INCLUDEDIR}`` ``include``
================== =============================== ====================== ================== =============================== ======================
To make your package compliant with distribution filesystem layout policies, it Projects wishing to follow the common practice of installing headers into a
is not recommended that you specify a ``DESTINATION`` for a target unless it project-specific subdirectory will need to provide a destination rather than
must be installed in a nonstandard location. That way, package maintainers can rely on the above.
control the install destination by setting the appropriate cache variables. In
any case, it is recommended that you use the :module:`GNUInstallDirs` variables To make packages compliant with distribution filesystem layout policies, if
in your ``DESTINATION`` arguments whenever possible. 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 In addition to the common options listed above, each target can accept
the following additional arguments: the following additional arguments:
...@@ -218,11 +243,9 @@ the following additional arguments: ...@@ -218,11 +243,9 @@ the following additional arguments:
install(TARGETS mylib install(TARGETS mylib
LIBRARY LIBRARY
DESTINATION lib
COMPONENT Libraries COMPONENT Libraries
NAMELINK_COMPONENT Development NAMELINK_COMPONENT Development
PUBLIC_HEADER PUBLIC_HEADER
DESTINATION include
COMPONENT Development COMPONENT Development
) )
...@@ -318,7 +341,7 @@ targets from other directories are up-to-date. You can use ...@@ -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 to ensure that such out-of-directory targets are built before the
subdirectory-specific install rules are run. 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 use "generator expressions" with the syntax ``$<...>``. See the
:manual:`cmake-generator-expressions(7)` manual for available expressions. :manual:`cmake-generator-expressions(7)` manual for available expressions.
...@@ -330,7 +353,8 @@ Installing Files ...@@ -330,7 +353,8 @@ Installing Files
.. code-block:: cmake .. code-block:: cmake
install(<FILES|PROGRAMS> files... [DESTINATION <dir> | TYPE <type>] install(<FILES|PROGRAMS> files...
TYPE <type> | DESTINATION <dir>
[PERMISSIONS permissions...] [PERMISSIONS permissions...]
[CONFIGURATIONS [Debug|Release|...]] [CONFIGURATIONS [Debug|Release|...]]
[COMPONENT <component>] [COMPONENT <component>]
...@@ -354,12 +378,14 @@ The list of ``files...`` given to ``FILES`` or ``PROGRAMS`` may use ...@@ -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 However, if any item begins in a generator expression it must evaluate
to a full path. to a full path.
Instead of specifying ``DESTINATION``, you may specify a generic file type Either a ``TYPE`` or a ``DESTINATION`` must be provided, but not both.
via the ``TYPE`` argument as listed below. If a type is selected and no A ``TYPE`` argument specifies the generic file type of the files being
destination is specified, the destination will default to either the installed. A destination will then be set automatically by taking the
appropriate variable from :module:`GNUInstallDirs` (if it is defined) or a corresponding variable from :module:`GNUInstallDirs`, or by using a
built-in default (if the variable is not defined.) These defaults are outlined built-in default if that variable is not defined. See the table below for
below: 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 ``TYPE`` Argument GNUInstallDirs Variable Built-In Default
...@@ -379,7 +405,9 @@ below: ...@@ -379,7 +405,9 @@ below:
``DOC`` ``${CMAKE_INSTALL_DOCDIR}`` ``<DATAROOT dir>/doc`` ``DOC`` ``${CMAKE_INSTALL_DOCDIR}`` ``<DATAROOT dir>/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 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 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 ...@@ -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 default. You cannot use ``DATAROOT`` as a ``TYPE`` parameter; please use
``DATA`` instead. ``DATA`` instead.
To make your package compliant with distribution filesystem layout policies, it To make packages compliant with distribution filesystem layout policies, if
is recommended that you specify one of the above generic file types, rather than projects must specify a ``DESTINATION``, it is recommended that they use a
a ``DESTINATION`` argument, unless the files must be installed in a nonstandard path that begins with the appropriate :module:`GNUInstallDirs` variable.
location. That way, package maintainers can control the install destination by This allows package maintainers to control the install destination by setting
setting the appropriate cache variables. In any case, it is recommended that you the appropriate cache variables. The following example shows how to follow
use the :module:`GNUInstallDirs` variables in your ``DESTINATION`` arguments this advice while installing headers to a project-specific subdirectory:
whenever possible.
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 use "generator expressions" with the syntax ``$<...>``. See the
:manual:`cmake-generator-expressions(7)` manual for available expressions. :manual:`cmake-generator-expressions(7)` manual for available expressions.
...@@ -406,7 +440,8 @@ Installing Directories ...@@ -406,7 +440,8 @@ Installing Directories
.. code-block:: cmake .. code-block:: cmake
install(DIRECTORY dirs... [DESTINATION <dir> | TYPE <type>] install(DIRECTORY dirs...
TYPE <type> | DESTINATION <dir>
[FILE_PERMISSIONS permissions...] [FILE_PERMISSIONS permissions...]
[DIRECTORY_PERMISSIONS permissions...] [DIRECTORY_PERMISSIONS permissions...]
[USE_SOURCE_PERMISSIONS] [OPTIONAL] [MESSAGE_NEVER] [USE_SOURCE_PERMISSIONS] [OPTIONAL] [MESSAGE_NEVER]
...@@ -477,12 +512,15 @@ will install the ``icons`` directory to ``share/myproj/icons`` and the ...@@ -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 file permissions, the scripts will be given specific permissions, and any
``CVS`` directories will be excluded. ``CVS`` directories will be excluded.
Instead of specifying ``DESTINATION``, you may specify a generic file type Either a ``TYPE`` or a ``DESTINATION`` must be provided, but not both.
via the ``TYPE`` argument as listed below. If a type is selected and no A ``TYPE`` argument specifies the generic file type of the files within the
destination is specified, the destination will default to either the listed directories being installed. A destination will then be set
appropriate variable from :module:`GNUInstallDirs` (if it is defined) or a automatically by taking the corresponding variable from
built-in default (if the variable is not defined.) These defaults are outlined :module:`GNUInstallDirs`, or by using a built-in default if that variable
below: 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 ``TYPE`` Argument GNUInstallDirs Variable Built-In Default
...@@ -502,24 +540,20 @@ below: ...@@ -502,24 +540,20 @@ below:
``DOC`` ``${CMAKE_INSTALL_DOCDIR}`` ``<DATAROOT dir>/doc`` ``DOC`` ``${CMAKE_INSTALL_DOCDIR}`` ``<DATAROOT dir>/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 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 a prefix. The ``DATAROOT`` prefix is calculated similarly to the types, with
``CMAKE_INSTALL_DATAROOTDIR`` as the variable and ``share`` as the built-in ``CMAKE_INSTALL_DATAROOTDIR`` as the variable and ``share`` as the built-in
default. You cannot use ``DATAROOT`` as a ``TYPE`` parameter; please use default. You cannot use ``DATAROOT`` as a ``TYPE`` parameter; please use
``DATA`` instead. ``DATA`` instead.
To make your package compliant with distribution filesystem layout policies, it To make packages compliant with distribution filesystem layout policies, if
is recommended that you specify one of the above generic file types, rather than projects must specify a ``DESTINATION``, it is recommended that they use a
a ``DESTINATION`` argument, unless the files must be installed in a nonstandard path that begins with the appropriate :module:`GNUInstallDirs` variable.
location. That way, package maintainers can control the install destination by This allows package maintainers to control the install destination by setting
setting the appropriate cache variables. In any case, it is recommended that you the appropriate cache variables.
use the :module:`GNUInstallDirs` variables in your ``DESTINATION`` arguments
whenever possible.
The list of ``dirs...`` given to ``DIRECTORY`` and the install destination The list of ``dirs...`` given to ``DIRECTORY`` and an install destination
given to the directory install ``DESTINATION`` may use "generator expressions" given as a ``DESTINATION`` argument may use "generator expressions"
with the syntax ``$<...>``. See the :manual:`cmake-generator-expressions(7)` with the syntax ``$<...>``. See the :manual:`cmake-generator-expressions(7)`
manual for available expressions. manual for available expressions.
......
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment