317 lines
14 KiB
ReStructuredText
317 lines
14 KiB
ReStructuredText
install
|
|
-------
|
|
|
|
Specify rules to run at install time.
|
|
|
|
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 properties for files and targets. Properties common to
|
|
multiple signatures are covered here but they are valid only for
|
|
signatures that specify them.
|
|
|
|
DESTINATION arguments 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 CMAKE_INSTALL_PREFIX. The
|
|
prefix can be relocated at install time using DESTDIR mechanism
|
|
explained in the CMAKE_INSTALL_PREFIX variable documentation.
|
|
|
|
PERMISSIONS arguments 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.
|
|
|
|
The CONFIGURATIONS argument specifies a list of build configurations
|
|
for which the install rule applies (Debug, Release, etc.).
|
|
|
|
The COMPONENT argument specifies 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. If COMPONENT
|
|
is not provided a default component "Unspecified" is created. The
|
|
default component name may be controlled with the
|
|
CMAKE_INSTALL_DEFAULT_COMPONENT_NAME variable.
|
|
|
|
The RENAME argument specifies 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.
|
|
|
|
The OPTIONAL argument specifies that it is not an error if the file to
|
|
be installed does not exist.
|
|
|
|
The TARGETS signature:
|
|
|
|
::
|
|
|
|
install(TARGETS targets... [EXPORT <export-name>]
|
|
[[ARCHIVE|LIBRARY|RUNTIME|FRAMEWORK|BUNDLE|
|
|
PRIVATE_HEADER|PUBLIC_HEADER|RESOURCE]
|
|
[DESTINATION <dir>]
|
|
[INCLUDES DESTINATION [<dir> ...]]
|
|
[PERMISSIONS permissions...]
|
|
[CONFIGURATIONS [Debug|Release|...]]
|
|
[COMPONENT <component>]
|
|
[OPTIONAL] [NAMELINK_ONLY|NAMELINK_SKIP]
|
|
] [...])
|
|
|
|
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 always treated as ARCHIVE targets. 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 INCLUDES DESTINATION specifies a list of directories
|
|
which will be added to the INTERFACE_INCLUDE_DIRECTORIES of the
|
|
<targets> when exported by install(EXPORT). If a relative path is
|
|
specified, it is treated as relative to the $<INSTALL_PREFIX>.
|
|
|
|
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 PRIVATE_HEADER,
|
|
PUBLIC_HEADER, and 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 VERSION and SOVERSION target properties for
|
|
details on creating versioned shared libraries.
|
|
|
|
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
|
|
|
|
::
|
|
|
|
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). See documentation of the install(EXPORT ...)
|
|
signature below for details.
|
|
|
|
Installing a target with EXCLUDE_FROM_ALL set to true has undefined
|
|
behavior.
|
|
|
|
The FILES signature:
|
|
|
|
::
|
|
|
|
install(FILES files... DESTINATION <dir>
|
|
[PERMISSIONS permissions...]
|
|
[CONFIGURATIONS [Debug|Release|...]]
|
|
[COMPONENT <component>]
|
|
[RENAME <name>] [OPTIONAL])
|
|
|
|
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 signature:
|
|
|
|
::
|
|
|
|
install(PROGRAMS files... DESTINATION <dir>
|
|
[PERMISSIONS permissions...]
|
|
[CONFIGURATIONS [Debug|Release|...]]
|
|
[COMPONENT <component>]
|
|
[RENAME <name>] [OPTIONAL])
|
|
|
|
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 DIRECTORY signature:
|
|
|
|
::
|
|
|
|
install(DIRECTORY dirs... DESTINATION <dir>
|
|
[FILE_PERMISSIONS permissions...]
|
|
[DIRECTORY_PERMISSIONS permissions...]
|
|
[USE_SOURCE_PERMISSIONS] [OPTIONAL]
|
|
[CONFIGURATIONS [Debug|Release|...]]
|
|
[COMPONENT <component>] [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.
|
|
|
|
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
|
|
|
|
::
|
|
|
|
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
|
|
|
|
::
|
|
|
|
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 SCRIPT and CODE signature:
|
|
|
|
::
|
|
|
|
install([[SCRIPT <file>] [CODE <code>]] [...])
|
|
|
|
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
|
|
|
|
::
|
|
|
|
install(CODE "MESSAGE(\"Sample install message.\")")
|
|
|
|
will print a message during installation.
|
|
|
|
The EXPORT signature:
|
|
|
|
::
|
|
|
|
install(EXPORT <export-name> DESTINATION <dir>
|
|
[NAMESPACE <namespace>] [FILE <name>.cmake]
|
|
[PERMISSIONS permissions...]
|
|
[CONFIGURATIONS [Debug|Release|...]]
|
|
[EXPORT_LINK_INTERFACE_LIBRARIES]
|
|
[COMPONENT <component>])
|
|
|
|
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 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.
|
|
|
|
The EXPORT form is useful to help outside projects use targets built
|
|
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)
|
|
|
|
will install the executable myexe to <prefix>/bin and code to import
|
|
it in the file "<prefix>/lib/myproj/myproj.cmake". 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 INSTALL_TARGETS command and the
|
|
target properties PRE_INSTALL_SCRIPT and POST_INSTALL_SCRIPT. It also
|
|
replaces the FILES forms of the INSTALL_FILES and INSTALL_PROGRAMS
|
|
commands. The processing order of these install rules relative to
|
|
those generated by INSTALL_TARGETS, INSTALL_FILES, and
|
|
INSTALL_PROGRAMS commands is not defined.
|