file

File manipulation command.

Synopsis

Reading
  file(READ <filename> <out-var> [...])
  file(STRINGS <filename> <out-var> [...])
  file(<HASH> <filename> <out-var>)
  file(TIMESTAMP <filename> <out-var> [...])

Writing
  file({WRITE | APPEND} <filename> <content>...)
  file({TOUCH | TOUCH_NOCREATE} [<file>...])
  file(GENERATE OUTPUT <output-file> [...])

Filesystem
  file({GLOB | GLOB_RECURSE} <out-var> [...] [<globbing-expr>...])
  file(RENAME <oldname> <newname>)
  file({REMOVE | REMOVE_RECURSE } [<files>...])
  file(MAKE_DIRECTORY [<dir>...])
  file({COPY | INSTALL} <file>... DESTINATION <dir> [...])
  file(SIZE <filename> <out-var>)
  file(READ_SYMLINK <linkname> <out-var>)
  file(CREATE_LINK <original> <linkname> [...])

Path Conversion
  file(RELATIVE_PATH <out-var> <directory> <file>)
  file({TO_CMAKE_PATH | TO_NATIVE_PATH} <path> <out-var>)

Transfer
  file(DOWNLOAD <url> <file> [...])
  file(UPLOAD <file> <url> [...])

Locking
  file(LOCK <path> [...])

Reading

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(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.

Writing

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(TOUCH [<files>...])
file(TOUCH_NOCREATE [<files>...])

Create a file with no content if it does not yet exist. If the file already exists, its access and/or modification will be updated to the time when the function call is executed.

Use TOUCH_NOCREATE to touch a file if it exists but not create it. If a file does not exist it will be silently ignored.

With TOUCH and TOUCH_NOCREATE the contents of an existing file will not be modified.

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 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. A relative path is treated with respect to the value of CMAKE_CURRENT_SOURCE_DIR. See policy CMP0070.

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 of CMAKE_CURRENT_BINARY_DIR. See policy CMP0070.

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.

Filesystem

file(GLOB <variable>
     [LIST_DIRECTORIES true|false] [RELATIVE <path>] [CONFIGURE_DEPENDS]
     [<globbing-expressions>...])
file(GLOB_RECURSE <variable> [FOLLOW_SYMLINKS]
     [LIST_DIRECTORIES true|false] [RELATIVE <path>] [CONFIGURE_DEPENDS]
     [<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.

If the CONFIGURE_DEPENDS flag is specified, CMake will add logic to the main build system check target to rerun the flagged GLOB commands at build time. If any of the outputs change, CMake will regenerate the build system.

By default GLOB lists directories - directories are omitted in result if LIST_DIRECTORIES is set to false.

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(<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(SIZE <filename> <variable>)

Determine the file size of the <filename> and put the result in <variable> variable. Requires that <filename> is a valid path pointing to a file and is readable.

file(READ_SYMLINK <linkname> <variable>)

This subcommand queries the symlink <linkname> and stores the path it points to in the result <variable>. If <linkname> does not exist or is not a symlink, CMake issues a fatal error.

Note that this command returns the raw symlink path and does not resolve a relative path. The following is an example of how to ensure that an absolute path is obtained:

set(linkname "/path/to/foo.sym")
file(READ_SYMLINK "${linkname}" result)
if(NOT IS_ABSOLUTE "${result}")
  get_filename_component(dir "${linkname}" DIRECTORY)
  set(result "${dir}/${result}")
endif()

file(CREATE_LINK <original> <linkname>
     [RESULT <result>] [COPY_ON_ERROR] [SYMBOLIC])

Create a link <linkname> that points to <original>. It will be a hard link by default, but providing the SYMBOLIC option results in a symbolic link instead. Hard links require that original exists and is a file, not a directory. If <linkname> already exists, it will be overwritten.

The <result> variable, if specified, receives the status of the operation. It is set to 0 upon success or an error message otherwise. If RESULT is not specified and the operation fails, a fatal error is emitted.

Specifying COPY_ON_ERROR enables copying the file as a fallback if creating the link fails. It can be useful for handling situations such as <original> and <linkname> being on different drives or mount points, which would make them unable to support a hard link.

Path Conversion

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.

Transfer

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.

NETRC <level>

Specify whether the .netrc file is to be used for operation. If this option is not specified, the value of the CMAKE_NETRC variable will be used instead. Valid levels are:

IGNORED

The .netrc file is ignored. This is the default.

OPTIONAL

The .netrc file is optional, and information in the URL is preferred. The file will be scanned to find which ever information is not specified in the URL.

REQUIRED

The .netrc file is required, and information in the URL is ignored.

NETRC_FILE <file>

Specify an alternative .netrc file to the one in your home directory, if the NETRC level is OPTIONAL or REQUIRED. If this option is not specified, the value of the CMAKE_NETRC_FILE variable will be used instead.

If neither NETRC option is given CMake will check variables CMAKE_NETRC and CMAKE_NETRC_FILE, respectively.

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.

Locking

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.