Kitware/CMake
1
0
Fork 0
mirror of https://github.com/Kitware/CMake.git synced 2025-05-08 14:29:03 +08:00
Code Issues Projects Releases Wiki Activity

Merge topic 'doc-install-DIRECTORY'

Browse Source 
0fb355143e Help: Reformat install(DIRECTORY) options as a definition list

Acked-by: Kitware Robot <kwrobot@kitware.com>
Merge-request: !10746
This commit is contained in:
Brad King 2025-05-06 13:44:51 +00:00 committed by Kitware Robot
commit 2a4c5923ef
1 changed files with 148 additions and 108 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

256
Help/command/install.rst
View File

@ -641,7 +641,7 @@ Signatures
.. code-block:: cmake .. code-block:: cmake
install(DIRECTORY dirs... install(DIRECTORY <dir>...
TYPE <type> | DESTINATION <dir> TYPE <type> | DESTINATION <dir>
[FILE_PERMISSIONS <permission>...] [FILE_PERMISSIONS <permission>...]
[DIRECTORY_PERMISSIONS <permission>...] [DIRECTORY_PERMISSIONS <permission>...]
@ -649,124 +649,164 @@ Signatures
[CONFIGURATIONS <config>...] [CONFIGURATIONS <config>...]
[COMPONENT <component>] [EXCLUDE_FROM_ALL] [COMPONENT <component>] [EXCLUDE_FROM_ALL]
[FILES_MATCHING] [FILES_MATCHING]
[[PATTERN <pattern> | REGEX <regex>] [<match-rule> <match-option>...]...
[EXCLUDE] [PERMISSIONS <permission>...]] [...]) )
The ``DIRECTORY`` form installs contents of one or more directories to a The ``DIRECTORY`` form installs contents of one or more directories to a
given destination. The directory structure is copied verbatim to the given destination. The directory structure is copied verbatim to the
destination. The last component of each directory name is appended to destination.
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) <Regex Specification>` 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.
Either a ``TYPE`` or a ``DESTINATION`` must be provided, but not both. 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 If no permissions is given, files will be given the default permissions
listed directories being installed. A destination will then be set specified in the `FILES`_ form of the command, and the directories
automatically by taking the corresponding variable from will be given the default permissions specified in the `PROGRAMS`_
:module:`GNUInstallDirs`, or by using a built-in default if that variable form of the command.
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.
======================= ================================== ========================= The options are:
``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}`` ``<LOCALSTATE dir>/run``
``DATA`` ``${CMAKE_INSTALL_DATADIR}`` ``<DATAROOT dir>``
``INFO`` ``${CMAKE_INSTALL_INFODIR}`` ``<DATAROOT dir>/info``
``LOCALE`` ``${CMAKE_INSTALL_LOCALEDIR}`` ``<DATAROOT dir>/locale``
``MAN`` ``${CMAKE_INSTALL_MANDIR}`` ``<DATAROOT dir>/man``
``DOC`` ``${CMAKE_INSTALL_DOCDIR}`` ``<DATAROOT dir>/doc``
``LIBEXEC`` ``${CMAKE_INSTALL_LIBEXECDIR}`` ``libexec``
======================= ================================== =========================
Note that some of the types' built-in defaults use the ``DATAROOT`` directory as ``<dir>...``
a prefix. The ``DATAROOT`` prefix is calculated similarly to the types, with The list of directories to be installed.
``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.
To make packages compliant with distribution filesystem layout policies, if The last component of each directory name is appended to the
projects must specify a ``DESTINATION``, it is strongly recommended that they use destination directory but a trailing slash may be used to avoid
a path that begins with the appropriate relative :module:`GNUInstallDirs` variable. this because it leaves the last component empty. Directory names
This allows package maintainers to control the install destination by setting given as relative paths are interpreted with respect to the current
the appropriate cache variables. 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 .. versionadded:: 3.5
An install destination given as a ``DESTINATION`` argument may The source ``<dir>...`` list may use "generator expressions" with the
use "generator expressions" with the syntax ``$<...>``. See the syntax ``$<...>``. See the :manual:`cmake-generator-expressions(7)`
:manual:`cmake-generator-expressions(7)` manual for available expressions. manual for available expressions.
.. versionadded:: 3.5 ``TYPE <type>``
The list of ``dirs...`` given to ``DIRECTORY`` may use Specifies the generic file type of the files within the listed
"generator expressions" too. 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}`` ``<LOCALSTATE dir>/run``
``DATA`` ``${CMAKE_INSTALL_DATADIR}`` ``<DATAROOT dir>``
``INFO`` ``${CMAKE_INSTALL_INFODIR}`` ``<DATAROOT dir>/info``
``LOCALE`` ``${CMAKE_INSTALL_LOCALEDIR}`` ``<DATAROOT dir>/locale``
``MAN`` ``${CMAKE_INSTALL_MANDIR}`` ``<DATAROOT dir>/man``
``DOC`` ``${CMAKE_INSTALL_DOCDIR}`` ``<DATAROOT dir>/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 <dir>``
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 ``<dir>`` may use "generator expressions" with the
syntax ``$<...>``. See the :manual:`cmake-generator-expressions(7)`
manual for available expressions.
``FILE_PERMISSIONS <permission>...``
Specify permissions given to files in the destination, where the
``<permission>`` names are documented among the `common options`_.
``DIRECTORY_PERMISSIONS <permission>...``
Specify permissions given to directories in the destination, where the
``<permission>`` 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 ``<match-rule>`` 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.
``<match-rule> <match-option>...``
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 ``<match-rule>``:
``PATTERN <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 <regex>``
Match any portion of the full path of a file with a
:ref:`regular expression <Regex Specification>`.
One may use ``/`` and ``$`` to limit matching to the end of a path.
Each ``<match-rule>`` may be followed by ``<match-option>`` 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 <permission>...``
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:: .. signature::
install(SCRIPT <file> [...]) install(SCRIPT <file> [...])