Merge topic 'doc-file-command'

d74ed543 Help: Format and revise file() command documentation

1 files changed, 266 insertions, 178 deletions

diff --git a/Help/command/file.rst b/Help/command/file.rst
index 83ade1d..14ca20c 100644
--- a/Help/command/file.rst
+++ b/Help/command/file.rst
@@ -3,211 +3,299 @@ file
 
 File manipulation command.
 
+------------------------------------------------------------------------------
+
 ::
 
-  file(WRITE filename "message to write"... )
-  file(APPEND filename "message to write"... )
-  file(READ filename variable [LIMIT numBytes] [OFFSET offset] [HEX])
-  file(<MD5|SHA1|SHA224|SHA256|SHA384|SHA512> filename variable)
-  file(STRINGS filename variable [LIMIT_COUNT num]
-       [LIMIT_INPUT numBytes] [LIMIT_OUTPUT numBytes]
-       [LENGTH_MINIMUM numBytes] [LENGTH_MAXIMUM numBytes]
-       [NEWLINE_CONSUME] [REGEX regex]
-       [NO_HEX_CONVERSION])
-  file(GLOB variable [RELATIVE path] [globbing expressions]...)
-  file(GLOB_RECURSE variable [RELATIVE path]
-       [FOLLOW_SYMLINKS] [globbing expressions]...)
-  file(RENAME <oldname> <newname>)
-  file(REMOVE [file1 ...])
-  file(REMOVE_RECURSE [file1 ...])
-  file(MAKE_DIRECTORY [directory1 directory2 ...])
-  file(RELATIVE_PATH variable directory file)
-  file(TO_CMAKE_PATH path result)
-  file(TO_NATIVE_PATH path result)
-  file(DOWNLOAD url file [INACTIVITY_TIMEOUT timeout]
-       [TIMEOUT timeout] [STATUS status] [LOG log] [SHOW_PROGRESS]
-       [EXPECTED_HASH ALGO=value] [EXPECTED_MD5 sum]
-       [TLS_VERIFY on|off] [TLS_CAINFO file])
-  file(UPLOAD filename url [INACTIVITY_TIMEOUT timeout]
-       [TIMEOUT timeout] [STATUS status] [LOG log] [SHOW_PROGRESS])
-  file(TIMESTAMP filename variable [<format string>] [UTC])
-  file(GENERATE OUTPUT output_file
-       <INPUT input_file|CONTENT input_content>
-       [CONDITION expression])
-
-WRITE will write a message into a file called 'filename'.  It
-overwrites the file if it already exists, and creates the file if it
-does not exist.  (If the file is a build input, use configure_file to
-update the file only when its content changes.)
-
-APPEND will write a message into a file same as WRITE, except it will
-append it to the end of the file
-
-READ will read the content of a file and store it into the variable.
-It will start at the given offset and read up to numBytes.  If the
-argument HEX is given, the binary data will be converted to
-hexadecimal representation and this will be stored in the variable.
-
-MD5, SHA1, SHA224, SHA256, SHA384, and SHA512 will compute a
-cryptographic hash of the content of a file.
-
-STRINGS will parse a list of ASCII strings from a file and store it in
-a variable.  Binary data in the file are ignored.  Carriage return
-(CR) characters are ignored.  It works also for Intel Hex and Motorola
-S-record files, which are automatically converted to binary format
-when reading them.  Disable this using NO_HEX_CONVERSION.
-
-LIMIT_COUNT sets the maximum number of strings to return.  LIMIT_INPUT
-sets the maximum number of bytes to read from the input file.
-LIMIT_OUTPUT sets the maximum number of bytes to store in the output
-variable.  LENGTH_MINIMUM sets the minimum length of a string to
-return.  Shorter strings are ignored.  LENGTH_MAXIMUM sets the maximum
-length of a string to return.  Longer strings are split into strings
-no longer than the maximum length.  NEWLINE_CONSUME allows newlines to
-be included in strings instead of terminating them.
-
-REGEX specifies a regular expression that a string must match to be
-returned.  Typical usage
+  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.
+(If the file is a build input, use the :command:`configure_file` command
+to update the file only when its content changes.)
+
+------------------------------------------------------------------------------
+
+::
+
+  file(READ <filename> <variable>
+       [OFFSET <offset>] [LIMIT <max-in>] [HEX])
+
+Read content from a file called ``<filename>`` and store it in a
+``<variable>``.  Optionally start from the given ``<offset>`` and
+read at most ``<max-in>`` bytes.  The ``HEX`` option causes data to
+be converted to a hexadecimal representation (useful for binary data).
+
+------------------------------------------------------------------------------
 
 ::
 
+  file(STRINGS <filename> <variable> [<options>...])
+
+Parse a list of ASCII strings from ``<filename>`` and store it in
+``<variable>``.  Binary data in the file are ignored.  Carriage return
+(``\r``, CR) characters are ignored.  The options are:
+
+``LENGTH_MAXIMUM <max-len>``
+ Consider only strings of at most a given length.
+
+``LENGTH_MINIMUM <min-len>``
+ Consider only strings of at least a given length.
+
+``LIMIT_COUNT <max-num>``
+ Limit the number of distinct strings to be extracted.
+
+``LIMIT_INPUT <max-in>``
+ Limit the number of input bytes to read from the file.
+
+``LIMIT_OUTPUT <max-out>``
+ Limit the number of total bytes to store in the ``<variable>``.
+
+``NEWLINE_CONSUME``
+ Treat newline characters (``\n``, LF) as part of string content
+ instead of terminating at them.
+
+``NO_HEX_CONVERSION``
+ Intel Hex and Motorola S-record files are automatically converted to
+ binary while reading unless this option is given.
+
+``REGEX <regex>``
+ Consider only strings that match the given regular expression.
+
+For example, the code
+
+.. code-block:: cmake
+
   file(STRINGS myfile.txt myfile)
 
-stores a list in the variable "myfile" in which each item is a line
+stores a list in the variable ``myfile`` in which each item is a line
 from the input file.
 
-GLOB will generate a list of all files that match the globbing
-expressions and store it into the variable.  Globbing expressions are
-similar to regular expressions, but much simpler.  If RELATIVE flag is
-specified for an expression, the results will be returned as a
-relative path to the given path.  (We do not recommend using GLOB to
-collect a list of source files from your source tree.  If no
-CMakeLists.txt file changes when a source is added or removed then the
-generated build system cannot know when to ask CMake to regenerate.)
+------------------------------------------------------------------------------
+
+::
+
+  file(<MD5|SHA1|SHA224|SHA256|SHA384|SHA512> <filename> <variable>)
+
+Compute a cryptographic hash of the content of ``<filename>`` and
+store it in a ``<variable>``.
+
+------------------------------------------------------------------------------
+
+::
+
+  file(GLOB <variable> [RELATIVE <path>] [<globbing-expressions>...])
+  file(GLOB_RECURSE <variable> [RELATIVE <path>]
+       [FOLLOW_SYMLINKS] [<globbing-expressions>...])
+
+Generate a list of files that match the ``<globbing-expressions>`` and
+store it into the ``<variable>``.  Globbing expressions are similar to
+regular expressions, but much simpler.  If ``RELATIVE`` flag is
+specified, the results will be returned as relative paths to the given
+path.
+
+.. note::
+  We do not recommend using GLOB to collect a list of source files from
+  your source tree.  If no CMakeLists.txt file changes when a source is
+  added or removed then the generated build system cannot know when to
+  ask CMake to regenerate.
+
+Examples of globbing expressions include::
+
+  *.cxx      - match all files with extension cxx
+  *.vt?      - match all files with extension vta,...,vtz
+  f[3-5].txt - match files f3.txt, f4.txt, f5.txt
+
+The ``GLOB_RECURSE`` mode will traverse all the subdirectories of the
+matched directory and match the files.  Subdirectories that are symlinks
+are only traversed if ``FOLLOW_SYMLINKS`` is given or policy
+:policy:`CMP0009` is not set to ``NEW``.
+
+Examples of recursive globbing include::
+
+  /dir/*.py  - match all python files in /dir and subdirectories
+
+------------------------------------------------------------------------------
+
+::
+
+  file(RENAME <oldname> <newname>)
+
+Move a file or directory within a filesystem from ``<oldname>`` to
+``<newname>``, replacing the destination atomically.
+
+------------------------------------------------------------------------------
+
+::
+
+  file(REMOVE [<files>...])
+  file(REMOVE_RECURSE [<files>...])
+
+Remove the given files.  The ``REMOVE_RECURSE`` mode will remove the given
+files and directories, also non-empty directories
+
+------------------------------------------------------------------------------
+
+::
+
+  file(MAKE_DIRECTORY [<directories>...])
 
-Examples of globbing expressions include:
+Create the given directories and their parents as needed.
+
+------------------------------------------------------------------------------
 
 ::
 
-   *.cxx      - match all files with extension cxx
-   *.vt?      - match all files with extension vta,...,vtz
-   f[3-5].txt - match files f3.txt, f4.txt, f5.txt
+  file(RELATIVE_PATH <variable> <directory> <file>)
 
-GLOB_RECURSE will generate a list similar to the regular GLOB, except
-it will traverse all the subdirectories of the matched directory and
-match the files.  Subdirectories that are symlinks are only traversed
-if FOLLOW_SYMLINKS is given or cmake policy CMP0009 is not set to NEW.
-See cmake --help-policy CMP0009 for more information.
+Compute the relative path from a ``<directory>`` to a ``<file>`` and
+store it in the ``<variable>``.
 
-Examples of recursive globbing include:
+------------------------------------------------------------------------------
 
 ::
 
-   /dir/*.py  - match all python files in /dir and subdirectories
-
-MAKE_DIRECTORY will create the given directories, also if their parent
-directories don't exist yet
-
-RENAME moves a file or directory within a filesystem, replacing the
-destination atomically.
-
-REMOVE will remove the given files, also in subdirectories
-
-REMOVE_RECURSE will remove the given files and directories, also
-non-empty directories
-
-RELATIVE_PATH will determine relative path from directory to the given
-file.
-
-TO_CMAKE_PATH will convert path into a cmake style path with unix /.
-The input can be a single path or a system path like "$ENV{PATH}".
-Note the double quotes around the ENV call TO_CMAKE_PATH only takes
-one argument.  This command will also convert the native list
-delimiters for a list of paths like the PATH environment variable.
-
-TO_NATIVE_PATH works just like TO_CMAKE_PATH, but will convert from a
-cmake style path into the native path style \ for windows and / for
-UNIX.
-
-DOWNLOAD will download the given URL to the given file.  If LOG var is
-specified a log of the download will be put in var.  If STATUS var is
-specified the status of the operation will be put in var.  The status
-is returned in a list of length 2.  The first element is the numeric
-return value for the operation, and the second element is a string
-value for the error.  A 0 numeric error means no error in the
-operation.  If TIMEOUT time is specified, the operation will timeout
-after time seconds, time should be specified as an integer.  The
-INACTIVITY_TIMEOUT specifies an integer number of seconds of
-inactivity after which the operation should terminate.  If
-EXPECTED_HASH ALGO=value is specified, the operation will verify that
-the downloaded file's actual hash matches the expected value, where
-ALGO is one of MD5, SHA1, SHA224, SHA256, SHA384, or SHA512.  If it
-does not match, the operation fails with an error.  ("EXPECTED_MD5
-sum" is short-hand for "EXPECTED_HASH MD5=sum".) If SHOW_PROGRESS is
-specified, progress information will be printed as status messages
-until the operation is complete.  For https URLs CMake must be built
-with OpenSSL.  TLS/SSL certificates are not checked by default.  Set
-TLS_VERIFY to ON to check certificates and/or use EXPECTED_HASH to
-verify downloaded content.  Set TLS_CAINFO to specify a custom
-Certificate Authority file.  If either TLS option is not given CMake
-will check variables CMAKE_TLS_VERIFY and CMAKE_TLS_CAINFO,
-respectively.
-
-UPLOAD will upload the given file to the given URL.  If LOG var is
-specified a log of the upload will be put in var.  If STATUS var is
-specified the status of the operation will be put in var.  The status
-is returned in a list of length 2.  The first element is the numeric
-return value for the operation, and the second element is a string
-value for the error.  A 0 numeric error means no error in the
-operation.  If TIMEOUT time is specified, the operation will timeout
-after time seconds, time should be specified as an integer.  The
-INACTIVITY_TIMEOUT specifies an integer number of seconds of
-inactivity after which the operation should terminate.  If
-SHOW_PROGRESS is specified, progress information will be printed as
-status messages until the operation is complete.
-
-TIMESTAMP will write a string representation of the modification time
-of filename to variable.
-
-Should the command be unable to obtain a timestamp variable will be
-set to the empty string "".
-
-See documentation of the string TIMESTAMP sub-command for more
-details.
-
-The file() command also provides COPY and INSTALL signatures:
+  file(TO_CMAKE_PATH "<path>" <variable>)
+  file(TO_NATIVE_PATH "<path>" <variable>)
+
+The ``TO_CMAKE_PATH`` mode converts a native ``<path>`` into a cmake-style
+path with forward-slashes (``/``).  The input can be a single path or a
+system search path like ``$ENV{PATH}``.  A search path will be converted
+to a cmake-style list separated by ``;`` characters.
+
+The ``TO_NATIVE_PATH`` mode converts a cmake-style ``<path>`` into a native
+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.
+
+------------------------------------------------------------------------------
+
+::
+
+  file(DOWNLOAD <url> <file> [<options>...])
+  file(UPLOAD   <file> <url> [<options>...])
+
+The ``DOWNLOAD`` mode downloads the given ``<url>`` to a local ``<file>``.
+The ``UPLOAD`` mode uploads a local ``<file>`` to a given ``<url>``.
+
+Options to both ``DOWNLOAD`` and ``UPLOAD`` are:
+
+``INACTIVITY_TIMEOUT <seconds>``
+  Terminate the operation after a period of inactivity.
+
+``LOG <variable>``
+  Store a human-readable log of the operation in a variable.
+
+``SHOW_PROGRESS``
+  Print progress information as status messages until the operation is
+  complete.
+
+``STATUS <variable>``
+  Store the resulting status of the operation in a variable.
+  The status is a ``;`` separated list of length 2.
+  The first element is the numeric return value for the operation,
+  and the second element is a string value for the error.
+  A ``0`` numeric error means no error in the operation.
+
+``TIMEOUT <seconds>``
+  Terminate the operation after a given total time has elapsed.
+
+Additional options to ``DOWNLOAD`` are:
+
+``EXPECTED_HASH ALGO=<value>``
+
+  Verify that the downloaded content hash matches the expected value, where
+  ``ALGO`` is one of ``MD5``, ``SHA1``, ``SHA224``, ``SHA256``, ``SHA384``, or
+  ``SHA512``.  If it does not match, the operation fails with an error.
+
+``EXPECTED_MD5 <value>``
+  Historical short-hand for ``EXPECTED_HASH MD5=<value>``.
+
+``TLS_VERIFY <ON|OFF>``
+  Specify whether to verify the server certificate for ``https://`` URLs.
+  The default is to *not* verify.
+
+``TLS_CAINFO <file>``
+  Specify a custom Certificate Authority file for ``https://`` URLs.
+
+For ``https://`` URLs CMake must be built with OpenSSL support.  ``TLS/SSL``
+certificates are not checked by default.  Set ``TLS_VERIFY`` to ``ON`` to
+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(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 <options>...)
+
+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.
+
+``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.
+
+Exactly one ``CONTENT`` or ``INPUT`` option must be given.  A specific
+``OUTPUT`` file may be named by at most one invocation of ``file(GENERATE)``.
+
+------------------------------------------------------------------------------
 
 ::
 
-  file(<COPY|INSTALL> files... DESTINATION <dir>
-       [FILE_PERMISSIONS permissions...]
-       [DIRECTORY_PERMISSIONS permissions...]
+  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...]] [...])
+        [EXCLUDE] [PERMISSIONS <permissions>...]] [...])
 
-The COPY signature copies files, directories, and symlinks to a
+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 install(DIRECTORY)
-command for documentation of permissions, PATTERN, REGEX, and EXCLUDE
-options.
-
-The INSTALL signature differs slightly from COPY: it prints status
-messages, and NO_SOURCE_PERMISSIONS is default.  Installation scripts
-generated by the install() command use this signature (with some
-undocumented options for internal use).
-
-GENERATE will write an <output_file> with content from an
-<input_file>, or from <input_content>.  The output is generated
-conditionally based on the content of the <condition>.  The file is
-written at CMake generate-time and the input may contain generator
-expressions.  The <condition>, <output_file> and <input_file> may also
-contain generator expressions.  The <condition> must evaluate to
-either '0' or '1'.  The <output_file> must evaluate to a unique name
-among all configurations and among all invocations of file(GENERATE).
+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, ``PATTERN``, ``REGEX``, and ``EXCLUDE`` options.
+
+The ``INSTALL`` signature differs slightly from ``COPY``: it prints
+status messages, and ``NO_SOURCE_PERMISSIONS`` is default.
+Installation scripts generated by the :command:`install` command
+use this signature (with some undocumented options for internal use).