diff options
Diffstat (limited to 'share/cmake-3.10/Help/command/install.rst')
| -rw-r--r-- | share/cmake-3.10/Help/command/install.rst | 380 |
1 files changed, 0 insertions, 380 deletions
diff --git a/share/cmake-3.10/Help/command/install.rst b/share/cmake-3.10/Help/command/install.rst deleted file mode 100644 index 58438b7..0000000 --- a/share/cmake-3.10/Help/command/install.rst +++ /dev/null @@ -1,380 +0,0 @@ -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|OBJECTS|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 six kinds of target files that may be installed: -``ARCHIVE``, ``LIBRARY``, ``RUNTIME``, ``OBJECTS``, ``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. Object -libraries are always treated as ``OBJECTS`` targets. -The ``ARCHIVE``, ``LIBRARY``, ``RUNTIME``, ``OBJECTS``, 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``, ``ARCHIVE``, or ``OBJECTS`` 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. |