Commit dd3e1a73 authored by Brad King's avatar Brad King 💬 Committed by Kitware Robot
Browse files

Merge topic 'doc-command-synopsis'

72814e46 Utilities/Sphinx: Make HTML links in parsed-literal blocks more obvious
08b4ea63 Help: Organize file command docs into sections
51c0e140 Help: Add Synopsis section to install, list, and string docs
0acd7051 Help: Improve list command signature group name for read operations
d5b2745b Help: Re-order file command docs
7d918b3c

 cmRST: Parse inline links and inline literals

Acked-by: Kitware Robot's avatarKitware Robot <kwrobot@kitware.com>
Merge-request: !2039
parents 42db3691 72814e46
Pipeline #100674 passed with stage
in 0 seconds
......@@ -3,23 +3,44 @@ file
File manipulation command.
------------------------------------------------------------------------------
Synopsis
^^^^^^^^
::
.. parsed-literal::
file(WRITE <filename> <content>...)
file(APPEND <filename> <content>...)
`Reading`_
file(`READ`_ <filename> <out-var> [...])
file(`STRINGS`_ <filename> <out-var> [...])
file(`\<HASH\> <HASH_>`_ <filename> <out-var>)
file(`TIMESTAMP`_ <filename> <out-var> [...])
Write ``<content>`` into a file called ``<filename>``. If the file does
not exist, it will be created. If the file already exists, ``WRITE``
mode will overwrite it and ``APPEND`` mode will append to the end.
Any directories in the path specified by ``<filename>`` that do not
exist will be created.
`Writing`_
file({`WRITE`_ | `APPEND`_} <filename> <content>...)
file({`TOUCH`_ | `TOUCH_NOCREATE`_} [<file>...])
file(`GENERATE`_ OUTPUT <output-file> [...])
If the file is a build input, use the :command:`configure_file` command
to update the file only when its content changes.
`Filesystem`_
file({`GLOB`_ | `GLOB_RECURSE`_} <out-var> [...] [<globbing-expr>...])
file(`RENAME`_ <oldname> <newname>)
file({`REMOVE`_ | `REMOVE_RECURSE`_ } [<files>...])
file(`MAKE_DIRECTORY`_ [<dir>...])
file({`COPY`_ | `INSTALL`_} <file>... DESTINATION <dir> [...])
`Path Conversion`_
file(`RELATIVE_PATH`_ <out-var> <directory> <file>)
file({`TO_CMAKE_PATH`_ | `TO_NATIVE_PATH`_} <path> <out-var>)
`Transfer`_
file(`DOWNLOAD`_ <url> <file> [...])
file(`UPLOAD`_ <file> <url> [...])
------------------------------------------------------------------------------
`Locking`_
file(`LOCK`_ <path> [...])
Reading
^^^^^^^
.. _READ:
::
......@@ -31,7 +52,7 @@ Read content from a file called ``<filename>`` and store it in a
read at most ``<max-in>`` bytes. The ``HEX`` option causes data to
be converted to a hexadecimal representation (useful for binary data).
------------------------------------------------------------------------------
.. _STRINGS:
::
......@@ -82,7 +103,7 @@ For example, the code
stores a list in the variable ``myfile`` in which each item is a line
from the input file.
------------------------------------------------------------------------------
.. _HASH:
::
......@@ -93,7 +114,108 @@ store it in a ``<variable>``. The supported ``<HASH>`` algorithm names
are those listed by the :ref:`string(\<HASH\>) <Supported Hash Algorithms>`
command.
------------------------------------------------------------------------------
.. _TIMESTAMP:
::
file(TIMESTAMP <filename> <variable> [<format>] [UTC])
Compute a string representation of the modification time of ``<filename>``
and store it in ``<variable>``. Should the command be unable to obtain a
timestamp variable will be set to the empty string ("").
See the :command:`string(TIMESTAMP)` command for documentation of
the ``<format>`` and ``UTC`` options.
Writing
^^^^^^^
.. _WRITE:
.. _APPEND:
::
file(WRITE <filename> <content>...)
file(APPEND <filename> <content>...)
Write ``<content>`` into a file called ``<filename>``. If the file does
not exist, it will be created. If the file already exists, ``WRITE``
mode will overwrite it and ``APPEND`` mode will append to the end.
Any directories in the path specified by ``<filename>`` that do not
exist will be created.
If the file is a build input, use the :command:`configure_file` command
to update the file only when its content changes.
.. _TOUCH:
.. _TOUCH_NOCREATE:
::
file(TOUCH [<files>...])
file(TOUCH_NOCREATE [<files>...])
Create a file with no content if it does not yet exist. If the file already
exists, its access and/or modification will be updated to the time when the
function call is executed.
Use TOUCH_NOCREATE to touch a file if it exists but not create it. If a file
does not exist it will be silently ignored.
With TOUCH and TOUCH_NOCREATE the contents of an existing file will not be
modified.
.. _GENERATE:
::
file(GENERATE OUTPUT output-file
<INPUT input-file|CONTENT content>
[CONDITION expression])
Generate an output file for each build configuration supported by the current
:manual:`CMake Generator <cmake-generators(7)>`. Evaluate
:manual:`generator expressions <cmake-generator-expressions(7)>`
from the input content to produce the output content. The options are:
``CONDITION <condition>``
Generate the output file for a particular configuration only if
the condition is true. The condition must be either ``0`` or ``1``
after evaluating generator expressions.
``CONTENT <content>``
Use the content given explicitly as input.
``INPUT <input-file>``
Use the content from a given file as input.
A relative path is treated with respect to the value of
:variable:`CMAKE_CURRENT_SOURCE_DIR`. See policy :policy:`CMP0070`.
``OUTPUT <output-file>``
Specify the output file name to generate. Use generator expressions
such as ``$<CONFIG>`` to specify a configuration-specific output file
name. Multiple configurations may generate the same output file only
if the generated content is identical. Otherwise, the ``<output-file>``
must evaluate to an unique name for each configuration.
A relative path (after evaluating generator expressions) is treated
with respect to the value of :variable:`CMAKE_CURRENT_BINARY_DIR`.
See policy :policy:`CMP0070`.
Exactly one ``CONTENT`` or ``INPUT`` option must be given. A specific
``OUTPUT`` file may be named by at most one invocation of ``file(GENERATE)``.
Generated files are modified and their timestamp updated on subsequent cmake
runs only if their content is changed.
Note also that ``file(GENERATE)`` does not create the output file until the
generation phase. The output file will not yet have been written when the
``file(GENERATE)`` command returns, it is written only after processing all
of a project's ``CMakeLists.txt`` files.
Filesystem
^^^^^^^^^^
.. _GLOB:
.. _GLOB_RECURSE:
::
......@@ -148,7 +270,7 @@ Examples of recursive globbing include::
/dir/*.py - match all python files in /dir and subdirectories
------------------------------------------------------------------------------
.. _RENAME:
::
......@@ -157,7 +279,8 @@ Examples of recursive globbing include::
Move a file or directory within a filesystem from ``<oldname>`` to
``<newname>``, replacing the destination atomically.
------------------------------------------------------------------------------
.. _REMOVE:
.. _REMOVE_RECURSE:
::
......@@ -168,7 +291,7 @@ Remove the given files. The ``REMOVE_RECURSE`` mode will remove the given
files and directories, also non-empty directories. No error is emitted if a
given file does not exist.
------------------------------------------------------------------------------
.. _MAKE_DIRECTORY:
::
......@@ -176,7 +299,44 @@ given file does not exist.
Create the given directories and their parents as needed.
------------------------------------------------------------------------------
.. _COPY:
.. _INSTALL:
::
file(<COPY|INSTALL> <files>... DESTINATION <dir>
[FILE_PERMISSIONS <permissions>...]
[DIRECTORY_PERMISSIONS <permissions>...]
[NO_SOURCE_PERMISSIONS] [USE_SOURCE_PERMISSIONS]
[FILES_MATCHING]
[[PATTERN <pattern> | REGEX <regex>]
[EXCLUDE] [PERMISSIONS <permissions>...]] [...])
The ``COPY`` signature copies files, directories, and symlinks to a
destination folder. Relative input paths are evaluated with respect
to the current source directory, and a relative destination is
evaluated with respect to the current build directory. Copying
preserves input file timestamps, and optimizes out a file if it exists
at the destination with the same timestamp. Copying preserves input
permissions unless explicit permissions or ``NO_SOURCE_PERMISSIONS``
are given (default is ``USE_SOURCE_PERMISSIONS``).
See the :command:`install(DIRECTORY)` command for documentation of
permissions, ``FILES_MATCHING``, ``PATTERN``, ``REGEX``, and
``EXCLUDE`` options. Copying directories preserves the structure
of their content even if options are used to select a subset of
files.
The ``INSTALL`` signature differs slightly from ``COPY``: it prints
status messages (subject to the :variable:`CMAKE_INSTALL_MESSAGE` variable),
and ``NO_SOURCE_PERMISSIONS`` is default.
Installation scripts generated by the :command:`install` command
use this signature (with some undocumented options for internal use).
Path Conversion
^^^^^^^^^^^^^^^
.. _RELATIVE_PATH:
::
......@@ -185,7 +345,8 @@ Create the given directories and their parents as needed.
Compute the relative path from a ``<directory>`` to a ``<file>`` and
store it in the ``<variable>``.
------------------------------------------------------------------------------
.. _TO_CMAKE_PATH:
.. _TO_NATIVE_PATH:
::
......@@ -203,7 +364,11 @@ path with platform-specific slashes (``\`` on Windows and ``/`` elsewhere).
Always use double quotes around the ``<path>`` to be sure it is treated
as a single argument to this command.
------------------------------------------------------------------------------
Transfer
^^^^^^^^
.. _DOWNLOAD:
.. _UPLOAD:
::
......@@ -290,116 +455,10 @@ check certificates and/or use ``EXPECTED_HASH`` to verify downloaded content.
If neither ``TLS`` option is given CMake will check variables
``CMAKE_TLS_VERIFY`` and ``CMAKE_TLS_CAINFO``, respectively.
------------------------------------------------------------------------------
::
file(TOUCH [<files>...])
file(TOUCH_NOCREATE [<files>...])
Create a file with no content if it does not yet exist. If the file already
exists, its access and/or modification will be updated to the time when the
function call is executed.
Use TOUCH_NOCREATE to touch a file if it exists but not create it. If a file
does not exist it will be silently ignored.
With TOUCH and TOUCH_NOCREATE the contents of an existing file will not be
modified.
------------------------------------------------------------------------------
::
file(TIMESTAMP <filename> <variable> [<format>] [UTC])
Compute a string representation of the modification time of ``<filename>``
and store it in ``<variable>``. Should the command be unable to obtain a
timestamp variable will be set to the empty string ("").
See the :command:`string(TIMESTAMP)` command for documentation of
the ``<format>`` and ``UTC`` options.
------------------------------------------------------------------------------
::
file(GENERATE OUTPUT output-file
<INPUT input-file|CONTENT content>
[CONDITION expression])
Generate an output file for each build configuration supported by the current
:manual:`CMake Generator <cmake-generators(7)>`. Evaluate
:manual:`generator expressions <cmake-generator-expressions(7)>`
from the input content to produce the output content. The options are:
``CONDITION <condition>``
Generate the output file for a particular configuration only if
the condition is true. The condition must be either ``0`` or ``1``
after evaluating generator expressions.
``CONTENT <content>``
Use the content given explicitly as input.
``INPUT <input-file>``
Use the content from a given file as input.
A relative path is treated with respect to the value of
:variable:`CMAKE_CURRENT_SOURCE_DIR`. See policy :policy:`CMP0070`.
``OUTPUT <output-file>``
Specify the output file name to generate. Use generator expressions
such as ``$<CONFIG>`` to specify a configuration-specific output file
name. Multiple configurations may generate the same output file only
if the generated content is identical. Otherwise, the ``<output-file>``
must evaluate to an unique name for each configuration.
A relative path (after evaluating generator expressions) is treated
with respect to the value of :variable:`CMAKE_CURRENT_BINARY_DIR`.
See policy :policy:`CMP0070`.
Exactly one ``CONTENT`` or ``INPUT`` option must be given. A specific
``OUTPUT`` file may be named by at most one invocation of ``file(GENERATE)``.
Generated files are modified and their timestamp updated on subsequent cmake
runs only if their content is changed.
Note also that ``file(GENERATE)`` does not create the output file until the
generation phase. The output file will not yet have been written when the
``file(GENERATE)`` command returns, it is written only after processing all
of a project's ``CMakeLists.txt`` files.
------------------------------------------------------------------------------
::
file(<COPY|INSTALL> <files>... DESTINATION <dir>
[FILE_PERMISSIONS <permissions>...]
[DIRECTORY_PERMISSIONS <permissions>...]
[NO_SOURCE_PERMISSIONS] [USE_SOURCE_PERMISSIONS]
[FILES_MATCHING]
[[PATTERN <pattern> | REGEX <regex>]
[EXCLUDE] [PERMISSIONS <permissions>...]] [...])
The ``COPY`` signature copies files, directories, and symlinks to a
destination folder. Relative input paths are evaluated with respect
to the current source directory, and a relative destination is
evaluated with respect to the current build directory. Copying
preserves input file timestamps, and optimizes out a file if it exists
at the destination with the same timestamp. Copying preserves input
permissions unless explicit permissions or ``NO_SOURCE_PERMISSIONS``
are given (default is ``USE_SOURCE_PERMISSIONS``).
See the :command:`install(DIRECTORY)` command for documentation of
permissions, ``FILES_MATCHING``, ``PATTERN``, ``REGEX``, and
``EXCLUDE`` options. Copying directories preserves the structure
of their content even if options are used to select a subset of
files.
The ``INSTALL`` signature differs slightly from ``COPY``: it prints
status messages (subject to the :variable:`CMAKE_INSTALL_MESSAGE` variable),
and ``NO_SOURCE_PERMISSIONS`` is default.
Installation scripts generated by the :command:`install` command
use this signature (with some undocumented options for internal use).
Locking
^^^^^^^
------------------------------------------------------------------------------
.. _LOCK:
::
......
install
-------
.. only:: html
.. contents::
Specify rules to run at install time.
This command accepts several signatures:
Synopsis
^^^^^^^^
* :ref:`install(TARGETS) <install-targets>`
* :ref:`install(FILES|PROGRAMS) <install-files>`
* :ref:`install(DIRECTORY) <install-directory>`
* :ref:`install(SCRIPT|CODE) <install-script>`
* :ref:`install(EXPORT|EXPORT_ANDROID_MK) <install-export>`
.. parsed-literal::
install(`TARGETS`_ <target>... [...])
install({`FILES`_ | `PROGRAMS`_} <file>... DESTINATION <dir> [...])
install(`DIRECTORY`_ <dir>... DESTINATION <dir> [...])
install(`SCRIPT`_ <file> [...])
install(`CODE`_ <code> [...])
install(`EXPORT`_ <export-name> DESTINATION <dir> [...])
Introduction
^^^^^^^^^^^^
......@@ -89,11 +89,11 @@ Command signatures that install files may print messages during
installation. Use the :variable:`CMAKE_INSTALL_MESSAGE` variable
to control which messages are printed.
.. _install-targets:
Installing Targets
^^^^^^^^^^^^^^^^^^
.. _TARGETS:
::
install(TARGETS targets... [EXPORT <export-name>]
......@@ -284,11 +284,12 @@ 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.
.. _install-files:
Installing Files
^^^^^^^^^^^^^^^^
.. _FILES:
.. _PROGRAMS:
::
install(<FILES|PROGRAMS> files... DESTINATION <dir>
......@@ -319,11 +320,11 @@ 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.
.. _install-directory:
Installing Directories
^^^^^^^^^^^^^^^^^^^^^^
.. _DIRECTORY:
::
install(DIRECTORY dirs... DESTINATION <dir>
......@@ -402,11 +403,12 @@ given to the directory install ``DESTINATION`` may use "generator expressions"
with the syntax ``$<...>``. See the :manual:`cmake-generator-expressions(7)`
manual for available expressions.
.. _install-script:
Custom Installation Logic
^^^^^^^^^^^^^^^^^^^^^^^^^
.. _CODE:
.. _SCRIPT:
::
install([[SCRIPT <file>] [CODE <code>]]
......@@ -425,11 +427,11 @@ example, the code
will print a message during installation.
.. _install-export:
Installing Exports
^^^^^^^^^^^^^^^^^^
.. _EXPORT:
::
install(EXPORT <export-name> DESTINATION <dir>
......
list
----
.. only:: html
List operations.
.. contents::
Synopsis
^^^^^^^^
List operations.
.. parsed-literal::
`Reading`_
list(`LENGTH`_ <list> <out-var>)
list(`GET`_ <list> <element index> [<index> ...] <out-var>)
list(`JOIN`_ <list> <glue> <out-var>)
list(`SUBLIST`_ <list> <begin> <length> <out-var>)
`Search`_
list(`FIND`_ <list> <value> <out-var>)
`Modification`_
list(`APPEND`_ <list> [<element>...])
list(`FILTER`_ <list> {INCLUDE | EXCLUDE} REGEX <regex>)
list(`INSERT`_ <list> <index> [<element>...])
list(`REMOVE_ITEM`_ <list> <value>...)
list(`REMOVE_AT`_ <list> <index>...)
list(`REMOVE_DUPLICATES`_ <list>)
list(`TRANSFORM`_ <list> <ACTION> [...])
`Ordering`_
list(`REVERSE`_ <list>)
list(`SORT`_ <list>)
Introduction
^^^^^^^^^^^^
The list subcommands ``APPEND``, ``INSERT``, ``FILTER``, ``REMOVE_AT``,
``REMOVE_ITEM``, ``REMOVE_DUPLICATES``, ``REVERSE`` and ``SORT`` may create
......@@ -33,11 +59,10 @@ scope. To propagate the results of these operations upwards, use
Be careful when counting with negative indices: they do not start from
0. -0 is equivalent to 0, the first list element.
Capacity and Element access
^^^^^^^^^^^^^^^^^^^^^^^^^^^
Reading
^^^^^^^
LENGTH
""""""
.. _LENGTH:
::
......@@ -45,8 +70,7 @@ LENGTH
Returns the list's length.
GET
"""
.. _GET:
::
......@@ -54,8 +78,7 @@ GET
Returns the list of elements specified by indices from the list.
JOIN
""""
.. _JOIN:
::
......@@ -65,8 +88,7 @@ Returns a string joining all list's elements using the glue string.
To join multiple strings, which are not part of a list, use ``JOIN`` operator
from :command:`string` command.
SUBLIST
"""""""
.. _SUBLIST:
::
......@@ -80,8 +102,7 @@ the remaining elements of the list starting at ``<begin>`` will be returned.
Search
^^^^^^
FIND
""""
.. _FIND:
::
......@@ -93,8 +114,7 @@ if it wasn't found.
Modification
^^^^^^^^^^^^
APPEND
""""""
.. _APPEND:
::
......@@ -102,8 +122,7 @@ APPEND
Appends elements to the list.
FILTER
""""""
.. _FILTER:
::
......@@ -115,8 +134,7 @@ In ``REGEX`` mode, items will be matched against the given regular expression.
For more information on regular expressions see also the
:command:`string` command.
INSERT
""""""
.. _INSERT:
::
......@@ -124,8 +142,7 @@ INSERT
Inserts elements to the list to the specified location.
REMOVE_ITEM
"""""""""""
.. _REMOVE_ITEM:
::
......@@ -133,8 +150,7 @@ REMOVE_ITEM
Removes the given items from the list.
REMOVE_AT
"""""""""
.. _REMOVE_AT:
::
......@@ -142,8 +158,7 @@ REMOVE_AT
Removes items at given indices from the list.
REMOVE_DUPLICATES
"""""""""""""""""
.. _REMOVE_DUPLICATES:
::
......@@ -151,8 +166,7 @@ REMOVE_DUPLICATES
Removes duplicated items in the list.
TRANSFORM
"""""""""
.. _TRANSFORM:
::
......@@ -224,11 +238,10 @@ expression will be transformed. ::
list(TRANSFORM <list> <ACTION> REGEX <regular_expression> ...)
Sorting
^^^^^^^
Ordering
^^^^^^^^