diff options
Diffstat (limited to 'Help/command/install.rst')
| -rw-r--r-- | Help/command/install.rst | 316 |
1 files changed, 316 insertions, 0 deletions
diff --git a/Help/command/install.rst b/Help/command/install.rst new file mode 100644 index 0000000..9b27cae --- /dev/null +++ b/Help/command/install.rst @@ -0,0 +1,316 @@ +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. |