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 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:
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(<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 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:
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.
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:
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 install(DIRECTORY) command for documentation of permissions, PATTERN, REGEX, and EXCLUDE options.
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).