summaryrefslogtreecommitdiffstats
path: root/Help/command/install.rst
diff options
context:
space:
mode:
authorKitware Robot <kwrobot@kitware.com>2013-10-15 15:17:36 (GMT)
committerBrad King <brad.king@kitware.com>2013-10-15 18:12:03 (GMT)
commitf051814ed0e63badbfd68049354f36259dbf4b49 (patch)
treef4e6f885f86c882d723a7dd53d2b702d0c7fdffb /Help/command/install.rst
parente94958e99c4dec26c86ce8b76d744c04ba960675 (diff)
downloadCMake-f051814ed0e63badbfd68049354f36259dbf4b49.zip
CMake-f051814ed0e63badbfd68049354f36259dbf4b49.tar.gz
CMake-f051814ed0e63badbfd68049354f36259dbf4b49.tar.bz2
Convert builtin help to reStructuredText source files
Run the convert-help.bash script to convert documentation: ./convert-help.bash "/path/to/CMake-build/bin" Then remove it.
Diffstat (limited to 'Help/command/install.rst')
-rw-r--r--Help/command/install.rst316
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.