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.
Any directories in the path specified by <filename>
that do not
exist will be created.
If the file is a build input, use the 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
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 string(<HASH>)
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. The results will be ordered lexicographically.
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
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 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. A0
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 byfile(<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 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
CMake Generator
. Evaluate
generator expressions
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
or1
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
CMAKE_CURRENT_SOURCE_DIR
. See policyCMP0070
.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 ofCMAKE_CURRENT_BINARY_DIR
. See policyCMP0070
.
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 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 CMAKE_INSTALL_MESSAGE
variable),
and NO_SOURCE_PERMISSIONS
is default.
Installation scripts generated by the 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.