summaryrefslogtreecommitdiffstats
path: root/Help
diff options
context:
space:
mode:
authorBrad King <brad.king@kitware.com>2018-05-04 13:12:07 (GMT)
committerBrad King <brad.king@kitware.com>2018-05-07 14:10:37 (GMT)
commit08b4ea639c877dee93d0a23a0fcf2ad41c7a1fcc (patch)
tree43cc35e6cdc1e7ffda4cb48a5264659b20f6387f /Help
parent51c0e1407c1317e8084c72fabebb60fffcaac99d (diff)
downloadCMake-08b4ea639c877dee93d0a23a0fcf2ad41c7a1fcc.zip
CMake-08b4ea639c877dee93d0a23a0fcf2ad41c7a1fcc.tar.gz
CMake-08b4ea639c877dee93d0a23a0fcf2ad41c7a1fcc.tar.bz2
Help: Organize file command docs into sections
Add a synopsis section at the top summarizing all signatures. Issue: #17948
Diffstat (limited to 'Help')
-rw-r--r--Help/command/file.rst91
1 files changed, 75 insertions, 16 deletions
diff --git a/Help/command/file.rst b/Help/command/file.rst
index 518ba9d..d4a6006 100644
--- a/Help/command/file.rst
+++ b/Help/command/file.rst
@@ -3,7 +3,44 @@ file
File manipulation command.
-------------------------------------------------------------------------------
+Synopsis
+^^^^^^^^
+
+.. parsed-literal::
+
+ `Reading`_
+ file(`READ`_ <filename> <out-var> [...])
+ file(`STRINGS`_ <filename> <out-var> [...])
+ file(`\<HASH\> <HASH_>`_ <filename> <out-var>)
+ file(`TIMESTAMP`_ <filename> <out-var> [...])
+
+ `Writing`_
+ file({`WRITE`_ | `APPEND`_} <filename> <content>...)
+ file({`TOUCH`_ | `TOUCH_NOCREATE`_} [<file>...])
+ file(`GENERATE`_ OUTPUT <output-file> [...])
+
+ `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:
::
@@ -15,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:
::
@@ -66,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:
::
@@ -77,7 +114,7 @@ store it in a ``<variable>``. The supported ``<HASH>`` algorithm names
are those listed by the :ref:`string(\<HASH\>) <Supported Hash Algorithms>`
command.
-------------------------------------------------------------------------------
+.. _TIMESTAMP:
::
@@ -90,7 +127,11 @@ 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:
::
@@ -106,7 +147,8 @@ 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:
::
@@ -123,7 +165,7 @@ does not exist it will be silently ignored.
With TOUCH and TOUCH_NOCREATE the contents of an existing file will not be
modified.
-------------------------------------------------------------------------------
+.. _GENERATE:
::
@@ -169,7 +211,11 @@ 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:
::
@@ -224,7 +270,7 @@ Examples of recursive globbing include::
/dir/*.py - match all python files in /dir and subdirectories
-------------------------------------------------------------------------------
+.. _RENAME:
::
@@ -233,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:
::
@@ -244,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:
::
@@ -252,7 +299,8 @@ given file does not exist.
Create the given directories and their parents as needed.
-------------------------------------------------------------------------------
+.. _COPY:
+.. _INSTALL:
::
@@ -285,7 +333,10 @@ 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:
::
@@ -294,7 +345,8 @@ use this signature (with some undocumented options for internal use).
Compute the relative path from a ``<directory>`` to a ``<file>`` and
store it in the ``<variable>``.
-------------------------------------------------------------------------------
+.. _TO_CMAKE_PATH:
+.. _TO_NATIVE_PATH:
::
@@ -312,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:
::
@@ -399,7 +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.
-------------------------------------------------------------------------------
+Locking
+^^^^^^^
+
+.. _LOCK:
::