| 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. |