d74ed5431a
Organize the documentation by sub-command to keep the signatures and their descriptions nearby. Use inline and explicit reST markup. Revise wording as necessary for the updated layout. Clarify behavior of the file(GENERATE) command w.r.t. conflicting file names.
302 lines
10 KiB
ReStructuredText
302 lines
10 KiB
ReStructuredText
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.
|
|
|
|
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(<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>...])
|
|
|
|
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.
|
|
|
|
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>...]
|
|
[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, ``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).
|