1 files changed, 368 insertions, 0 deletions
diff --git a/Help/command/file.rst b/Help/command/file.rst
new file mode 100644
index 0000000..3e669c2
--- /dev/null
+++ b/Help/command/file.rst
@@ -0,0 +1,368 @@
+file
+----
+
+File manipulation command.
+
+------------------------------------------------------------------------------
+
+::
+
+  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.
+
+``ENCODING <encoding-type>``
+ Consider strings of a given encoding.  Currently supported encodings are:
+ UTF-8, UTF-16LE, UTF-16BE, UTF-32LE, UTF-32BE.  If the ENCODING option
+ is not provided and the file has a Byte Order Mark, the ENCODING option
+ will be defaulted to respect the Byte Order Mark.
+
+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
+from the input file.
+
+------------------------------------------------------------------------------
+
+::
+
+  file(<HASH> <filename> <variable>)
+
+Compute a cryptographic hash of the content of ``<filename>`` and
+store it in a ``<variable>``.  The supported ``<HASH>`` algorithm names
+are those listed by the :ref:`string(\<HASH\>) <Supported Hash Algorithms>`
+command.
+
+------------------------------------------------------------------------------
+
+::
+
+  file(GLOB <variable>
+       [LIST_DIRECTORIES true|false] [RELATIVE <path>]
+       [<globbing-expressions>...])
+  file(GLOB_RECURSE <variable> [FOLLOW_SYMLINKS]
+       [LIST_DIRECTORIES true|false] [RELATIVE <path>]
+       [<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.  No specific order of results is defined other than that it is
+deterministic.  If order is important then sort the list explicitly
+(e.g. using the :command:`list(SORT)` command).
+
+By default ``GLOB`` lists directories - directories are omited in result if
+``LIST_DIRECTORIES`` is set to false.
+
+.. 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``.
+
+By default ``GLOB_RECURSE`` omits directories from result list - setting
+``LIST_DIRECTORIES`` to true adds directories to result list.
+If ``FOLLOW_SYMLINKS`` is given or policy :policy:`CMP0009` is not set to
+``OLD`` then ``LIST_DIRECTORIES`` treats symlinks as directories.
+
+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. No error is emitted if a
+given file does not exist.
+
+------------------------------------------------------------------------------
+
+::
+
+  file(MAKE_DIRECTORY [<directories>...])
+
+Create the given directories and their parents as needed.
+
+------------------------------------------------------------------------------
+
+::
+
+  file(RELATIVE_PATH <variable> <directory> <file>)
+
+Compute the relative path from a ``<directory>`` to a ``<file>`` and
+store it in the ``<variable>``.
+
+------------------------------------------------------------------------------
+
+::
+
+  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.
+
+``USERPWD <username>:<password>``
+  Set username and password for operation.
+
+``HTTPHEADER <HTTP-header>``
+  HTTP header for operation. Suboption can be repeated several times.
+
+Additional options to ``DOWNLOAD`` are:
+
+``EXPECTED_HASH ALGO=<value>``
+
+  Verify that the downloaded content hash matches the expected value, where
+  ``ALGO`` is one of the algorithms supported by ``file(<HASH>)``.
+  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 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.
+
+``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)``.
+Generated files are modified on subsequent cmake runs only if their content
+is changed.
+
+------------------------------------------------------------------------------
+
+::
+
+  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).
+
+------------------------------------------------------------------------------
+
+::
+
+  file(LOCK <path> [DIRECTORY] [RELEASE]
+       [GUARD <FUNCTION|FILE|PROCESS>]
+       [RESULT_VARIABLE <variable>]
+       [TIMEOUT <seconds>])
+
+Lock a file specified by ``<path>`` if no ``DIRECTORY`` option present and file
+``<path>/cmake.lock`` otherwise. File will be locked for scope defined by
+``GUARD`` option (default value is ``PROCESS``). ``RELEASE`` option can be used
+to unlock file explicitly. If option ``TIMEOUT`` is not specified CMake will
+wait until lock succeed or until fatal error occurs. If ``TIMEOUT`` is set to
+``0`` lock will be tried once and result will be reported immediately. If
+``TIMEOUT`` is not ``0`` CMake will try to lock file for the period specified
+by ``<seconds>`` value. Any errors will be interpreted as fatal if there is no
+``RESULT_VARIABLE`` option. Otherwise result will be stored in ``<variable>``
+and will be ``0`` on success or error message on failure.
+
+Note that lock is advisory - there is no guarantee that other processes will
+respect this lock, i.e. lock synchronize two or more CMake instances sharing
+some modifiable resources. Similar logic applied to ``DIRECTORY`` option -
+locking parent directory doesn't prevent other ``LOCK`` commands to lock any
+child directory or file.
+
+Trying to lock file twice is not allowed.  Any intermediate directories and
+file itself will be created if they not exist.  ``GUARD`` and ``TIMEOUT``
+options ignored on ``RELEASE`` operation.