|
|
|
|
@ -9,11 +9,11 @@ Synopsis
|
|
|
|
|
.. parsed-literal::
|
|
|
|
|
|
|
|
|
|
install(`TARGETS`_ <target>... [...])
|
|
|
|
|
install({`FILES`_ | `PROGRAMS`_} <file>... DESTINATION <dir> [...])
|
|
|
|
|
install(`DIRECTORY`_ <dir>... DESTINATION <dir> [...])
|
|
|
|
|
install({`FILES`_ | `PROGRAMS`_} <file>... [...])
|
|
|
|
|
install(`DIRECTORY`_ <dir>... [...])
|
|
|
|
|
install(`SCRIPT`_ <file> [...])
|
|
|
|
|
install(`CODE`_ <code> [...])
|
|
|
|
|
install(`EXPORT`_ <export-name> DESTINATION <dir> [...])
|
|
|
|
|
install(`EXPORT`_ <export-name> [...])
|
|
|
|
|
|
|
|
|
|
Introduction
|
|
|
|
|
^^^^^^^^^^^^
|
|
|
|
|
@ -99,9 +99,10 @@ Windows platforms are unaffected.
|
|
|
|
|
Installing Targets
|
|
|
|
|
^^^^^^^^^^^^^^^^^^
|
|
|
|
|
|
|
|
|
|
.. _`install(TARGETS)`:
|
|
|
|
|
.. _TARGETS:
|
|
|
|
|
|
|
|
|
|
::
|
|
|
|
|
.. code-block:: cmake
|
|
|
|
|
|
|
|
|
|
install(TARGETS targets... [EXPORT <export-name>]
|
|
|
|
|
[[ARCHIVE|LIBRARY|RUNTIME|OBJECTS|FRAMEWORK|BUNDLE|
|
|
|
|
|
@ -147,13 +148,13 @@ project. There are several kinds of target files that may be installed:
|
|
|
|
|
property are treated as ``FRAMEWORK`` targets on macOS.
|
|
|
|
|
|
|
|
|
|
``BUNDLE``
|
|
|
|
|
Executables marked with the ``MACOSX_BUNDLE`` property are treated as
|
|
|
|
|
Executables marked with the :prop_tgt:`MACOSX_BUNDLE` property are treated as
|
|
|
|
|
``BUNDLE`` targets on macOS.
|
|
|
|
|
|
|
|
|
|
``PUBLIC_HEADER``
|
|
|
|
|
Any ``PUBLIC_HEADER`` files associated with a library are installed in
|
|
|
|
|
Any :prop_tgt:`PUBLIC_HEADER` files associated with a library are installed in
|
|
|
|
|
the destination specified by the ``PUBLIC_HEADER`` argument on non-Apple
|
|
|
|
|
platforms. Rules defined by this argument are ignored for ``FRAMEWORK``
|
|
|
|
|
platforms. Rules defined by this argument are ignored for :prop_tgt:`FRAMEWORK`
|
|
|
|
|
libraries on Apple platforms because the associated files are installed
|
|
|
|
|
into the appropriate locations inside the framework folder. See
|
|
|
|
|
:prop_tgt:`PUBLIC_HEADER` for details.
|
|
|
|
|
@ -172,6 +173,54 @@ 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 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
|
|
|
|
|
================== =============================== ======================
|
|
|
|
|
``RUNTIME`` ``${CMAKE_INSTALL_BINDIR}`` ``bin``
|
|
|
|
|
``LIBRARY`` ``${CMAKE_INSTALL_LIBDIR}`` ``lib``
|
|
|
|
|
``ARCHIVE`` ``${CMAKE_INSTALL_LIBDIR}`` ``lib``
|
|
|
|
|
``PRIVATE_HEADER`` ``${CMAKE_INSTALL_INCLUDEDIR}`` ``include``
|
|
|
|
|
``PUBLIC_HEADER`` ``${CMAKE_INSTALL_INCLUDEDIR}`` ``include``
|
|
|
|
|
================== =============================== ======================
|
|
|
|
|
|
|
|
|
|
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:
|
|
|
|
|
|
|
|
|
|
@ -195,11 +244,9 @@ the following additional arguments:
|
|
|
|
|
|
|
|
|
|
install(TARGETS mylib
|
|
|
|
|
LIBRARY
|
|
|
|
|
DESTINATION lib
|
|
|
|
|
COMPONENT Libraries
|
|
|
|
|
NAMELINK_COMPONENT Development
|
|
|
|
|
PUBLIC_HEADER
|
|
|
|
|
DESTINATION include
|
|
|
|
|
COMPONENT Development
|
|
|
|
|
)
|
|
|
|
|
|
|
|
|
|
@ -242,18 +289,20 @@ the following additional arguments:
|
|
|
|
|
is not recommended to use ``NAMELINK_SKIP`` in conjunction with
|
|
|
|
|
``NAMELINK_COMPONENT``.
|
|
|
|
|
|
|
|
|
|
The ``install(TARGETS)`` command can also accept the following options at the
|
|
|
|
|
The `install(TARGETS)`_ command can also accept the following options at the
|
|
|
|
|
top level:
|
|
|
|
|
|
|
|
|
|
``EXPORT``
|
|
|
|
|
This option associates the installed target files with an export called
|
|
|
|
|
``<export-name>``. It must appear before any target options. To actually
|
|
|
|
|
install the export file itself, call ``install(EXPORT)``, documented below.
|
|
|
|
|
install the export file itself, call `install(EXPORT)`_, documented below.
|
|
|
|
|
See documentation of the :prop_tgt:`EXPORT_NAME` target property to change
|
|
|
|
|
the name of the exported target.
|
|
|
|
|
|
|
|
|
|
``INCLUDES DESTINATION``
|
|
|
|
|
This option specifies a list of directories which will be added to the
|
|
|
|
|
:prop_tgt:`INTERFACE_INCLUDE_DIRECTORIES` target property of the
|
|
|
|
|
``<targets>`` when exported by the :command:`install(EXPORT)` command. If a
|
|
|
|
|
``<targets>`` when exported by the `install(EXPORT)`_ command. If a
|
|
|
|
|
relative path is specified, it is treated as relative to the
|
|
|
|
|
``$<INSTALL_PREFIX>``.
|
|
|
|
|
|
|
|
|
|
@ -287,7 +336,7 @@ targets that link to the object libraries in their implementation.
|
|
|
|
|
Installing a target with the :prop_tgt:`EXCLUDE_FROM_ALL` target property
|
|
|
|
|
set to ``TRUE`` has undefined behavior.
|
|
|
|
|
|
|
|
|
|
:command:`install(TARGETS)` can install targets that were created in
|
|
|
|
|
`install(TARGETS)`_ can install targets that were created in
|
|
|
|
|
other directories. When using such cross-directory install rules, running
|
|
|
|
|
``make install`` (or similar) from a subdirectory will not guarantee that
|
|
|
|
|
targets from other directories are up-to-date. You can use
|
|
|
|
|
@ -295,19 +344,22 @@ 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.
|
|
|
|
|
|
|
|
|
|
Installing Files
|
|
|
|
|
^^^^^^^^^^^^^^^^
|
|
|
|
|
|
|
|
|
|
.. _`install(FILES)`:
|
|
|
|
|
.. _`install(PROGRAMS)`:
|
|
|
|
|
.. _FILES:
|
|
|
|
|
.. _PROGRAMS:
|
|
|
|
|
|
|
|
|
|
::
|
|
|
|
|
.. code-block:: cmake
|
|
|
|
|
|
|
|
|
|
install(<FILES|PROGRAMS> files... DESTINATION <dir>
|
|
|
|
|
install(<FILES|PROGRAMS> files...
|
|
|
|
|
TYPE <type> | DESTINATION <dir>
|
|
|
|
|
[PERMISSIONS permissions...]
|
|
|
|
|
[CONFIGURATIONS [Debug|Release|...]]
|
|
|
|
|
[COMPONENT <component>]
|
|
|
|
|
@ -331,18 +383,71 @@ 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.
|
|
|
|
|
|
|
|
|
|
The install destination given to the files install ``DESTINATION`` may
|
|
|
|
|
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
|
|
|
|
|
======================= ================================== =========================
|
|
|
|
|
``BIN`` ``${CMAKE_INSTALL_BINDIR}`` ``bin``
|
|
|
|
|
``SBIN`` ``${CMAKE_INSTALL_SBINDIR}`` ``sbin``
|
|
|
|
|
``LIB`` ``${CMAKE_INSTALL_LIBDIR}`` ``lib``
|
|
|
|
|
``INCLUDE`` ``${CMAKE_INSTALL_INCLUDEDIR}`` ``include``
|
|
|
|
|
``SYSCONF`` ``${CMAKE_INSTALL_SYSCONFDIR}`` ``etc``
|
|
|
|
|
``SHAREDSTATE`` ``${CMAKE_INSTALL_SHARESTATEDIR}`` ``com``
|
|
|
|
|
``LOCALSTATE`` ``${CMAKE_INSTALL_LOCALSTATEDIR}`` ``var``
|
|
|
|
|
``RUNSTATE`` ``${CMAKE_INSTALL_RUNSTATEDIR}`` ``<LOCALSTATE dir>/run``
|
|
|
|
|
``DATA`` ``${CMAKE_INSTALL_DATADIR}`` ``<DATAROOT dir>``
|
|
|
|
|
``INFO`` ``${CMAKE_INSTALL_INFODIR}`` ``<DATAROOT dir>/info``
|
|
|
|
|
``LOCALE`` ``${CMAKE_INSTALL_LOCALEDIR}`` ``<DATAROOT dir>/locale``
|
|
|
|
|
``MAN`` ``${CMAKE_INSTALL_MANDIR}`` ``<DATAROOT dir>/man``
|
|
|
|
|
``DOC`` ``${CMAKE_INSTALL_DOCDIR}`` ``<DATAROOT dir>/doc``
|
|
|
|
|
======================= ================================== =========================
|
|
|
|
|
|
|
|
|
|
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
|
|
|
|
|
``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 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:
|
|
|
|
|
|
|
|
|
|
.. 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.
|
|
|
|
|
|
|
|
|
|
Installing Directories
|
|
|
|
|
^^^^^^^^^^^^^^^^^^^^^^
|
|
|
|
|
|
|
|
|
|
.. _`install(DIRECTORY)`:
|
|
|
|
|
.. _DIRECTORY:
|
|
|
|
|
|
|
|
|
|
::
|
|
|
|
|
.. code-block:: cmake
|
|
|
|
|
|
|
|
|
|
install(DIRECTORY dirs... DESTINATION <dir>
|
|
|
|
|
install(DIRECTORY dirs...
|
|
|
|
|
TYPE <type> | DESTINATION <dir>
|
|
|
|
|
[FILE_PERMISSIONS permissions...]
|
|
|
|
|
[DIRECTORY_PERMISSIONS permissions...]
|
|
|
|
|
[USE_SOURCE_PERMISSIONS] [OPTIONAL] [MESSAGE_NEVER]
|
|
|
|
|
@ -413,18 +518,60 @@ 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.
|
|
|
|
|
|
|
|
|
|
The list of ``dirs...`` given to ``DIRECTORY`` and the install destination
|
|
|
|
|
given to the directory install ``DESTINATION`` may use "generator expressions"
|
|
|
|
|
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
|
|
|
|
|
======================= ================================== =========================
|
|
|
|
|
``BIN`` ``${CMAKE_INSTALL_BINDIR}`` ``bin``
|
|
|
|
|
``SBIN`` ``${CMAKE_INSTALL_SBINDIR}`` ``sbin``
|
|
|
|
|
``LIB`` ``${CMAKE_INSTALL_LIBDIR}`` ``lib``
|
|
|
|
|
``INCLUDE`` ``${CMAKE_INSTALL_INCLUDEDIR}`` ``include``
|
|
|
|
|
``SYSCONF`` ``${CMAKE_INSTALL_SYSCONFDIR}`` ``etc``
|
|
|
|
|
``SHAREDSTATE`` ``${CMAKE_INSTALL_SHARESTATEDIR}`` ``com``
|
|
|
|
|
``LOCALSTATE`` ``${CMAKE_INSTALL_LOCALSTATEDIR}`` ``var``
|
|
|
|
|
``RUNSTATE`` ``${CMAKE_INSTALL_RUNSTATEDIR}`` ``<LOCALSTATE dir>/run``
|
|
|
|
|
``DATA`` ``${CMAKE_INSTALL_DATADIR}`` ``<DATAROOT dir>``
|
|
|
|
|
``INFO`` ``${CMAKE_INSTALL_INFODIR}`` ``<DATAROOT dir>/info``
|
|
|
|
|
``LOCALE`` ``${CMAKE_INSTALL_LOCALEDIR}`` ``<DATAROOT dir>/locale``
|
|
|
|
|
``MAN`` ``${CMAKE_INSTALL_MANDIR}`` ``<DATAROOT dir>/man``
|
|
|
|
|
``DOC`` ``${CMAKE_INSTALL_DOCDIR}`` ``<DATAROOT dir>/doc``
|
|
|
|
|
======================= ================================== =========================
|
|
|
|
|
|
|
|
|
|
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 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 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.
|
|
|
|
|
|
|
|
|
|
Custom Installation Logic
|
|
|
|
|
^^^^^^^^^^^^^^^^^^^^^^^^^
|
|
|
|
|
|
|
|
|
|
.. _`install(CODE)`:
|
|
|
|
|
.. _`install(SCRIPT)`:
|
|
|
|
|
.. _CODE:
|
|
|
|
|
.. _SCRIPT:
|
|
|
|
|
|
|
|
|
|
::
|
|
|
|
|
.. code-block:: cmake
|
|
|
|
|
|
|
|
|
|
install([[SCRIPT <file>] [CODE <code>]]
|
|
|
|
|
[COMPONENT <component>] [EXCLUDE_FROM_ALL] [...])
|
|
|
|
|
@ -442,12 +589,18 @@ example, the code
|
|
|
|
|
|
|
|
|
|
will print a message during installation.
|
|
|
|
|
|
|
|
|
|
``<file>`` or ``<code>`` may use "generator expressions" with the syntax
|
|
|
|
|
``$<...>`` (in the case of ``<file>``, this refers to their use in the file
|
|
|
|
|
name, not the file's contents). See the
|
|
|
|
|
:manual:`cmake-generator-expressions(7)` manual for available expressions.
|
|
|
|
|
|
|
|
|
|
Installing Exports
|
|
|
|
|
^^^^^^^^^^^^^^^^^^
|
|
|
|
|
|
|
|
|
|
.. _`install(EXPORT)`:
|
|
|
|
|
.. _EXPORT:
|
|
|
|
|
|
|
|
|
|
::
|
|
|
|
|
.. code-block:: cmake
|
|
|
|
|
|
|
|
|
|
install(EXPORT <export-name> DESTINATION <dir>
|
|
|
|
|
[NAMESPACE <namespace>] [[FILE <name>.cmake]|
|
|
|
|
|
@ -461,7 +614,7 @@ Installing Exports
|
|
|
|
|
The ``EXPORT`` form generates and installs a CMake file containing code to
|
|
|
|
|
import targets from the installation tree into another project.
|
|
|
|
|
Target installations are associated with the export ``<export-name>``
|
|
|
|
|
using the ``EXPORT`` option of the ``install(TARGETS)`` signature
|
|
|
|
|
using the ``EXPORT`` option of the `install(TARGETS)`_ signature
|
|
|
|
|
documented above. The ``NAMESPACE`` option will prepend ``<namespace>`` to
|
|
|
|
|
the target names as they are written to the import file. By default
|
|
|
|
|
the generated file will be called ``<export-name>.cmake`` but the ``FILE``
|
|
|
|
|
@ -507,9 +660,9 @@ and installed by the current project. For example, the code
|
|
|
|
|
|
|
|
|
|
install(TARGETS myexe EXPORT myproj DESTINATION bin)
|
|
|
|
|
install(EXPORT myproj NAMESPACE mp_ DESTINATION lib/myproj)
|
|
|
|
|
install(EXPORT_ANDROID_MK myexp DESTINATION share/ndk-modules)
|
|
|
|
|
install(EXPORT_ANDROID_MK myproj DESTINATION share/ndk-modules)
|
|
|
|
|
|
|
|
|
|
will install the executable myexe to ``<prefix>/bin`` and code to import
|
|
|
|
|
will install the executable ``myexe`` to ``<prefix>/bin`` and code to import
|
|
|
|
|
it in the file ``<prefix>/lib/myproj/myproj.cmake`` and
|
|
|
|
|
``<prefix>/share/ndk-modules/Android.mk``. An outside project
|
|
|
|
|
may load this file with the include command and reference the ``myexe``
|
|
|
|
|
|
Felix Geyer
5 years ago