install | |
------- | |
.. only:: html | |
.. contents:: | |
Specify rules to run at install time. | |
Introduction | |
^^^^^^^^^^^^ | |
This command generates installation rules for a project. Rules | |
specified by calls to this command within a source directory are | |
executed in order during installation. The order across directories | |
is not defined. | |
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 | |
signatures that specify them. The common options are: | |
``DESTINATION`` | |
Specify the directory on disk to which a file will be installed. | |
If a full path (with a leading slash or drive letter) is given | |
it is used directly. If a relative path is given it is interpreted | |
relative to the value of the :variable:`CMAKE_INSTALL_PREFIX` variable. | |
The prefix can be relocated at install time using the ``DESTDIR`` | |
mechanism explained in the :variable:`CMAKE_INSTALL_PREFIX` variable | |
documentation. | |
``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`` | |
Specify a list of build configurations for which the install rule | |
applies (Debug, Release, etc.). | |
``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 | |
the given component name will be executed. During a full installation | |
all components are installed unless marked with ``EXCLUDE_FROM_ALL``. | |
If ``COMPONENT`` is not provided a default component "Unspecified" is | |
created. The default component name may be controlled with the | |
:variable:`CMAKE_INSTALL_DEFAULT_COMPONENT_NAME` variable. | |
``EXCLUDE_FROM_ALL`` | |
Specify that the file is excluded from a full installation and only | |
installed as part of a component-specific installation | |
``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. | |
``OPTIONAL`` | |
Specify that it is not an error if the file to be installed does | |
not exist. | |
Command signatures that install files may print messages during | |
installation. Use the :variable:`CMAKE_INSTALL_MESSAGE` variable | |
to control which messages are printed. | |
Installing Targets | |
^^^^^^^^^^^^^^^^^^ | |
:: | |
install(TARGETS targets... [EXPORT <export-name>] | |
[[ARCHIVE|LIBRARY|RUNTIME|FRAMEWORK|BUNDLE| | |
PRIVATE_HEADER|PUBLIC_HEADER|RESOURCE] | |
[DESTINATION <dir>] | |
[PERMISSIONS permissions...] | |
[CONFIGURATIONS [Debug|Release|...]] | |
[COMPONENT <component>] | |
[OPTIONAL] [EXCLUDE_FROM_ALL] | |
[NAMELINK_ONLY|NAMELINK_SKIP] | |
] [...] | |
[INCLUDES DESTINATION [<dir> ...]] | |
) | |
The ``TARGETS`` form specifies rules for installing targets from a | |
project. There are five kinds of target files that may be installed: | |
``ARCHIVE``, ``LIBRARY``, ``RUNTIME``, ``FRAMEWORK``, and ``BUNDLE``. | |
Executables are treated as ``RUNTIME`` targets, except that those | |
marked with the ``MACOSX_BUNDLE`` property are treated as ``BUNDLE`` | |
targets on OS X. Static libraries are treated as ``ARCHIVE`` targets, | |
except that those marked with the ``FRAMEWORK`` property are treated | |
as ``FRAMEWORK`` targets on OS X. | |
Module libraries are always treated as ``LIBRARY`` targets. | |
For non-DLL platforms shared libraries are treated as ``LIBRARY`` | |
targets, except that those marked with the ``FRAMEWORK`` property are | |
treated as ``FRAMEWORK`` targets on OS X. For DLL platforms the DLL | |
part of a shared library is treated as a ``RUNTIME`` target and the | |
corresponding import library is treated as an ``ARCHIVE`` target. | |
All Windows-based systems including Cygwin are DLL platforms. | |
The ``ARCHIVE``, ``LIBRARY``, ``RUNTIME``, and ``FRAMEWORK`` arguments | |
change the type of target to which the subsequent properties apply. | |
If none is given the 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). | |
The ``PRIVATE_HEADER``, ``PUBLIC_HEADER``, and ``RESOURCE`` arguments | |
cause subsequent properties to be applied to installing a ``FRAMEWORK`` | |
shared library target's associated files on non-Apple platforms. Rules | |
defined by these arguments are ignored on Apple platforms because the | |
associated files are installed into the appropriate locations inside | |
the framework folder. See documentation of the | |
:prop_tgt:`PRIVATE_HEADER`, :prop_tgt:`PUBLIC_HEADER`, and | |
:prop_tgt:`RESOURCE` target properties for details. | |
Either ``NAMELINK_ONLY`` or ``NAMELINK_SKIP`` may be specified as a | |
``LIBRARY`` option. On some platforms a versioned shared library | |
has a symbolic link such as:: | |
lib<name>.so -> lib<name>.so.1 | |
where ``lib<name>.so.1`` is the soname of the library and ``lib<name>.so`` | |
is a "namelink" allowing linkers to find the library when given | |
``-l<name>``. The ``NAMELINK_ONLY`` option causes installation of only the | |
namelink when a library target is installed. The ``NAMELINK_SKIP`` option | |
causes installation of library files other than the namelink when a | |
library target is installed. When neither option is given both | |
portions are installed. On platforms where versioned shared libraries | |
do not have namelinks or when a library is not versioned the | |
``NAMELINK_SKIP`` option installs the library and the ``NAMELINK_ONLY`` | |
option installs nothing. See the :prop_tgt:`VERSION` and | |
:prop_tgt:`SOVERSION` target properties for details on creating versioned | |
shared libraries. | |
The ``INCLUDES DESTINATION`` 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 relative path is | |
specified, it is treated as relative to the ``$<INSTALL_PREFIX>``. | |
This is independent of the rest of the argument groups and does | |
not actually install anything. | |
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 ``<prefix>/bin`` and ``myStaticLib`` to | |
``<prefix>/lib/static``. On non-DLL platforms ``mySharedLib`` will be | |
installed to ``<prefix>/lib`` and ``/some/full/path``. On DLL platforms | |
the ``mySharedLib`` DLL will be installed to ``<prefix>/bin`` and | |
``/some/full/path`` and its import library will be installed to | |
``<prefix>/lib/static`` and ``/some/full/path``. | |
The ``EXPORT`` option associates the installed target files with an | |
export called ``<export-name>``. It must appear before any ``RUNTIME``, | |
``LIBRARY``, or ``ARCHIVE`` options. To actually install the export | |
file itself, call ``install(EXPORT)``, documented below. | |
Installing a target with the :prop_tgt:`EXCLUDE_FROM_ALL` target property | |
set to ``TRUE`` has undefined behavior. | |
The install destination given to the target install ``DESTINATION`` may | |
use "generator expressions" with the syntax ``$<...>``. See the | |
:manual:`cmake-generator-expressions(7)` manual for available expressions. | |
Installing Files | |
^^^^^^^^^^^^^^^^ | |
:: | |
install(<FILES|PROGRAMS> files... DESTINATION <dir> | |
[PERMISSIONS permissions...] | |
[CONFIGURATIONS [Debug|Release|...]] | |
[COMPONENT <component>] | |
[RENAME <name>] [OPTIONAL] [EXCLUDE_FROM_ALL]) | |
The ``FILES`` form specifies rules for installing files for a project. | |
File names given as relative paths are interpreted with respect to the | |
current source directory. Files installed by this form are by default | |
given permissions ``OWNER_WRITE``, ``OWNER_READ``, ``GROUP_READ``, and | |
``WORLD_READ`` if no ``PERMISSIONS`` argument is given. | |
The ``PROGRAMS`` form is identical to the ``FILES`` form except that the | |
default permissions for the installed file also include ``OWNER_EXECUTE``, | |
``GROUP_EXECUTE``, and ``WORLD_EXECUTE``. This form is intended to install | |
programs that are not targets, such as shell scripts. Use the ``TARGETS`` | |
form to install targets built within the project. | |
The list of ``files...`` given to ``FILES`` or ``PROGRAMS`` may use | |
"generator expressions" with the syntax ``$<...>``. See the | |
:manual:`cmake-generator-expressions(7)` manual for available expressions. | |
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 | |
use "generator expressions" with the syntax ``$<...>``. See the | |
:manual:`cmake-generator-expressions(7)` manual for available expressions. | |
Installing Directories | |
^^^^^^^^^^^^^^^^^^^^^^ | |
:: | |
install(DIRECTORY dirs... DESTINATION <dir> | |
[FILE_PERMISSIONS permissions...] | |
[DIRECTORY_PERMISSIONS permissions...] | |
[USE_SOURCE_PERMISSIONS] [OPTIONAL] [MESSAGE_NEVER] | |
[CONFIGURATIONS [Debug|Release|...]] | |
[COMPONENT <component>] [EXCLUDE_FROM_ALL] | |
[FILES_MATCHING] | |
[[PATTERN <pattern> | REGEX <regex>] | |
[EXCLUDE] [PERMISSIONS permissions...]] [...]) | |
The ``DIRECTORY`` form installs contents of one or more directories to a | |
given destination. The directory structure is copied verbatim to the | |
destination. The last component of each directory name is appended to | |
the destination directory but a trailing slash may be used to avoid | |
this because it leaves the last component empty. Directory names | |
given as relative paths are interpreted with respect to the current | |
source directory. If no input directory names are given the | |
destination directory will be created but nothing will be installed | |
into it. The ``FILE_PERMISSIONS`` and ``DIRECTORY_PERMISSIONS`` options | |
specify permissions given to files and directories in the destination. | |
If ``USE_SOURCE_PERMISSIONS`` is specified and ``FILE_PERMISSIONS`` is not, | |
file permissions will be copied from the source directory structure. | |
If no permissions are specified files will be given the default | |
permissions specified in the ``FILES`` form of the command, and the | |
directories will be given the default permissions specified in the | |
``PROGRAMS`` form of the command. | |
The ``MESSAGE_NEVER`` option disables file installation status output. | |
Installation of directories may be controlled with fine granularity | |
using the ``PATTERN`` or ``REGEX`` options. These "match" options specify a | |
globbing pattern or regular expression to match directories or files | |
encountered within input directories. They may be used to apply | |
certain options (see below) to a subset of the files and directories | |
encountered. The full path to each input file or directory (with | |
forward slashes) is matched against the expression. A ``PATTERN`` will | |
match only complete file names: the portion of the full path matching | |
the pattern must occur at the end of the file name and be preceded by | |
a slash. A ``REGEX`` will match any portion of the full path but it may | |
use ``/`` and ``$`` to simulate the ``PATTERN`` behavior. By default all | |
files and directories are installed whether or not they are matched. | |
The ``FILES_MATCHING`` option may be given before the first match option | |
to disable installation of files (but not directories) not matched by | |
any expression. For example, the code | |
.. code-block:: cmake | |
install(DIRECTORY src/ DESTINATION include/myproj | |
FILES_MATCHING PATTERN "*.h") | |
will extract and install header files from a source tree. | |
Some options may follow a ``PATTERN`` or ``REGEX`` expression and are applied | |
only to files or directories matching them. The ``EXCLUDE`` option will | |
skip the matched file or directory. The ``PERMISSIONS`` option overrides | |
the permissions setting for the matched file or directory. For | |
example the code | |
.. code-block:: cmake | |
install(DIRECTORY icons scripts/ DESTINATION share/myproj | |
PATTERN "CVS" EXCLUDE | |
PATTERN "scripts/*" | |
PERMISSIONS OWNER_EXECUTE OWNER_WRITE OWNER_READ | |
GROUP_EXECUTE GROUP_READ) | |
will install the ``icons`` directory to ``share/myproj/icons`` and the | |
``scripts`` directory to ``share/myproj``. The icons will get default | |
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" | |
with the syntax ``$<...>``. See the :manual:`cmake-generator-expressions(7)` | |
manual for available expressions. | |
Custom Installation Logic | |
^^^^^^^^^^^^^^^^^^^^^^^^^ | |
:: | |
install([[SCRIPT <file>] [CODE <code>]] | |
[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 | |
interpreted with respect to the current source directory. The ``CODE`` | |
form will invoke the given CMake code during installation. Code is | |
specified as a single argument inside a double-quoted string. For | |
example, the code | |
.. code-block:: cmake | |
install(CODE "MESSAGE(\"Sample install message.\")") | |
will print a message during installation. | |
Installing Exports | |
^^^^^^^^^^^^^^^^^^ | |
:: | |
install(EXPORT <export-name> DESTINATION <dir> | |
[NAMESPACE <namespace>] [[FILE <name>.cmake]| | |
[EXPORT_ANDROID_MK <name>.mk]] | |
[PERMISSIONS permissions...] | |
[CONFIGURATIONS [Debug|Release|...]] | |
[EXPORT_LINK_INTERFACE_LIBRARIES] | |
[COMPONENT <component>] | |
[EXCLUDE_FROM_ALL]) | |
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 | |
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`` | |
option may be used to specify a different name. The value given to | |
the ``FILE`` option must be a file name with the ``.cmake`` extension. | |
If a ``CONFIGURATIONS`` option is given then the file will only be installed | |
when one of the named configurations is installed. Additionally, the | |
generated import file will reference only the matching target | |
configurations. The ``EXPORT_LINK_INTERFACE_LIBRARIES`` keyword, if | |
present, causes the contents of the properties matching | |
``(IMPORTED_)?LINK_INTERFACE_LIBRARIES(_<CONFIG>)?`` to be exported, when | |
policy :policy:`CMP0022` is ``NEW``. If a ``COMPONENT`` option is | |
specified that does not match that given to the targets associated with | |
``<export-name>`` the behavior is undefined. If a library target is | |
included in the export but a target to which it links is not included | |
the behavior is unspecified. | |
In additon to cmake language files, the ``EXPORT_ANDROID_MK`` option maybe | |
used to specifiy an export to the android ndk build system. The Android | |
NDK supports the use of prebuilt libraries, both static and shared. This | |
allows cmake to build the libraries of a project and make them available | |
to an ndk build system complete with transitive dependencies, include flags | |
and defines required to use the libraries. | |
The ``EXPORT`` form is useful to help outside projects use targets built | |
and installed by the current project. For example, the code | |
.. code-block:: cmake | |
install(TARGETS myexe EXPORT myproj DESTINATION bin) | |
install(EXPORT myproj NAMESPACE mp_ DESTINATION lib/myproj) | |
install(EXPORT_ANDROID_MK myexp DESTINATION share/ndk-modules) | |
will install the executable myexe to ``<prefix>/bin`` and code to import | |
it in the file ``<prefix>/lib/myproj/myproj.cmake`` and | |
``<prefix>/lib/share/ndk-modules/Android.mk``. An outside project | |
may load this file with the include command and reference the ``myexe`` | |
executable from the installation tree using the imported target name | |
``mp_myexe`` as if the target were built in its own tree. | |
.. note:: | |
This command supercedes the :command:`install_targets` command and | |
the :prop_tgt:`PRE_INSTALL_SCRIPT` and :prop_tgt:`POST_INSTALL_SCRIPT` | |
target properties. It also replaces the ``FILES`` forms of the | |
:command:`install_files` and :command:`install_programs` commands. | |
The processing order of these install rules relative to | |
those generated by :command:`install_targets`, | |
:command:`install_files`, and :command:`install_programs` commands | |
is not defined. |