diff --git a/Help/command/install.rst b/Help/command/install.rst index 59b3b96fae..781fbbab84 100644 --- a/Help/command/install.rst +++ b/Help/command/install.rst @@ -641,7 +641,7 @@ Signatures .. code-block:: cmake - install(DIRECTORY dirs... + install(DIRECTORY ... TYPE | DESTINATION [FILE_PERMISSIONS ...] [DIRECTORY_PERMISSIONS ...] @@ -649,124 +649,164 @@ Signatures [CONFIGURATIONS ...] [COMPONENT ] [EXCLUDE_FROM_ALL] [FILES_MATCHING] - [[PATTERN | REGEX ] - [EXCLUDE] [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. - - .. versionadded:: 3.1 - 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 doc/myproj - FILES_MATCHING PATTERN "*.png") - - will extract and install images from a source tree. - - Some options may follow a ``PATTERN`` or ``REGEX`` expression as described - under :ref:`string(REGEX) ` 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. + destination. Either a ``TYPE`` or a ``DESTINATION`` must be provided, but not both. - A ``TYPE`` argument specifies the generic file type of the files within the - listed directories being installed. A destination will then be set - automatically by taking the corresponding variable from - :module:`GNUInstallDirs`, or by using a built-in default if that variable - is not defined. See the table below for the supported file types and their - corresponding variables and built-in defaults. Projects can provide a - ``DESTINATION`` argument instead of a file type if they wish to explicitly - define the install destination. + If no permissions is given, 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. - ======================= ================================== ========================= - ``TYPE`` Argument GNUInstallDirs Variable Built-In Default - ======================= ================================== ========================= - ``BIN`` ``${CMAKE_INSTALL_BINDIR}`` ``bin`` - ``SBIN`` ``${CMAKE_INSTALL_SBINDIR}`` ``sbin`` - ``LIB`` ``${CMAKE_INSTALL_LIBDIR}`` ``lib`` - ``INCLUDE`` ``${CMAKE_INSTALL_INCLUDEDIR}`` ``include`` - ``SYSCONF`` ``${CMAKE_INSTALL_SYSCONFDIR}`` ``etc`` - ``SHAREDSTATE`` ``${CMAKE_INSTALL_SHARESTATEDIR}`` ``com`` - ``LOCALSTATE`` ``${CMAKE_INSTALL_LOCALSTATEDIR}`` ``var`` - ``RUNSTATE`` ``${CMAKE_INSTALL_RUNSTATEDIR}`` ``/run`` - ``DATA`` ``${CMAKE_INSTALL_DATADIR}`` ```` - ``INFO`` ``${CMAKE_INSTALL_INFODIR}`` ``/info`` - ``LOCALE`` ``${CMAKE_INSTALL_LOCALEDIR}`` ``/locale`` - ``MAN`` ``${CMAKE_INSTALL_MANDIR}`` ``/man`` - ``DOC`` ``${CMAKE_INSTALL_DOCDIR}`` ``/doc`` - ``LIBEXEC`` ``${CMAKE_INSTALL_LIBEXECDIR}`` ``libexec`` - ======================= ================================== ========================= + The options are: - Note that some of the types' built-in defaults use the ``DATAROOT`` directory as - a prefix. The ``DATAROOT`` prefix is calculated similarly to the types, with - ``CMAKE_INSTALL_DATAROOTDIR`` as the variable and ``share`` as the built-in - default. You cannot use ``DATAROOT`` as a ``TYPE`` parameter; please use - ``DATA`` instead. + ``...`` + The list of directories to be installed. - To make packages compliant with distribution filesystem layout policies, if - projects must specify a ``DESTINATION``, it is strongly recommended that they use - a path that begins with the appropriate relative :module:`GNUInstallDirs` variable. - This allows package maintainers to control the install destination by setting - the appropriate cache variables. + 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. - .. versionadded:: 3.4 - An install destination given as a ``DESTINATION`` argument may - use "generator expressions" with the syntax ``$<...>``. See the - :manual:`cmake-generator-expressions(7)` manual for available expressions. + .. versionadded:: 3.5 + The source ``...`` list may use "generator expressions" with the + syntax ``$<...>``. See the :manual:`cmake-generator-expressions(7)` + manual for available expressions. - .. versionadded:: 3.5 - The list of ``dirs...`` given to ``DIRECTORY`` may use - "generator expressions" too. + ``TYPE `` + Specifies the generic file type of the files within the listed + directories being installed. A destination will then be set + automatically by taking the corresponding variable from + :module:`GNUInstallDirs`, or by using a built-in default if that + variable is not defined. See the table below for the supported + file types and their corresponding variables and built-in defaults. + Projects can provide a ``DESTINATION`` argument instead of a file + type if they wish to explicitly define the install destination. - .. versionadded:: 3.31 - The ``TYPE`` argument now supports type ``LIBEXEC``. + ======================= ================================== ========================= + ``TYPE`` Argument GNUInstallDirs Variable Built-In Default + ======================= ================================== ========================= + ``BIN`` ``${CMAKE_INSTALL_BINDIR}`` ``bin`` + ``SBIN`` ``${CMAKE_INSTALL_SBINDIR}`` ``sbin`` + ``LIB`` ``${CMAKE_INSTALL_LIBDIR}`` ``lib`` + ``INCLUDE`` ``${CMAKE_INSTALL_INCLUDEDIR}`` ``include`` + ``SYSCONF`` ``${CMAKE_INSTALL_SYSCONFDIR}`` ``etc`` + ``SHAREDSTATE`` ``${CMAKE_INSTALL_SHARESTATEDIR}`` ``com`` + ``LOCALSTATE`` ``${CMAKE_INSTALL_LOCALSTATEDIR}`` ``var`` + ``RUNSTATE`` ``${CMAKE_INSTALL_RUNSTATEDIR}`` ``/run`` + ``DATA`` ``${CMAKE_INSTALL_DATADIR}`` ```` + ``INFO`` ``${CMAKE_INSTALL_INFODIR}`` ``/info`` + ``LOCALE`` ``${CMAKE_INSTALL_LOCALEDIR}`` ``/locale`` + ``MAN`` ``${CMAKE_INSTALL_MANDIR}`` ``/man`` + ``DOC`` ``${CMAKE_INSTALL_DOCDIR}`` ``/doc`` + ``LIBEXEC`` ``${CMAKE_INSTALL_LIBEXECDIR}`` ``libexec`` + ======================= ================================== ========================= + + Note that some of the types' built-in defaults use the ``DATAROOT`` + directory as a prefix. The ``DATAROOT`` prefix is calculated similarly + to the types, with ``CMAKE_INSTALL_DATAROOTDIR`` as the variable and + ``share`` as the built-in default. You cannot use ``DATAROOT`` as a + ``TYPE`` parameter; please use ``DATA`` instead. + + .. versionadded:: 3.31 + The ``LIBEXEC`` type. + + ``DESTINATION `` + The destination directory, as documented among the `common options`_. + + To make packages compliant with distribution filesystem layout + policies, if projects must specify a ``DESTINATION``, it is + strongly recommended that they use a path that begins with the + appropriate relative :module:`GNUInstallDirs` variable. + This allows package maintainers to control the install destination + by setting the appropriate cache variables. + + .. versionadded:: 3.4 + The destination ```` may use "generator expressions" with the + syntax ``$<...>``. See the :manual:`cmake-generator-expressions(7)` + manual for available expressions. + + ``FILE_PERMISSIONS ...`` + Specify permissions given to files in the destination, where the + ```` names are documented among the `common options`_. + + ``DIRECTORY_PERMISSIONS ...`` + Specify permissions given to directories in the destination, where the + ```` names are documented among the `common options`_. + + ``USE_SOURCE_PERMISSIONS`` + If specified, and ``FILE_PERMISSIONS`` is not, file permissions will + be copied from the source directory structure. + + ``MESSAGE_NEVER`` + .. versionadded:: 3.1 + + Disable file installation status output. + + ``FILES_MATCHING`` + This option may be given before the first ```` to + disable installation of files (but not directories) not matched + by any expression. For example, the code + + .. code-block:: cmake + + install(DIRECTORY src/ DESTINATION doc/myproj + FILES_MATCHING PATTERN "*.png") + + will extract and install images from a source tree. + + `` ...`` + Installation of directories may be controlled with fine granularity + using rules that 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. All files + and directories are installed whether or not they are matched, + unless the above ``FILES_MATCHING`` option is given. + + The full path to each input file or directory, with forward slashes, + may be matched by a ````: + + ``PATTERN `` + Match complete file names using a globbing pattern. The portion of + the full path matching the pattern must occur at the end of the file + name and be preceded by a slash (which is not part of the pattern). + + ``REGEX `` + Match any portion of the full path of a file with a + :ref:`regular expression `. + One may use ``/`` and ``$`` to limit matching to the end of a path. + + Each ```` may be followed by ```` arguments. + The match options apply to the files or directories matched by the rule. + The match options are: + + ``EXCLUDE`` + Exclude the matched file or directory from installation. + + ``PERMISSIONS ...`` + Ovrerride 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. .. signature:: install(SCRIPT [...])