You type touch afile.txt in a directory that contains no files. what will be the effect?

Synopsis¶

Reading
  file(READ   [...])
  file(STRINGS   [...])
  file(  )
  file(TIMESTAMP   [...])
  file(GET_RUNTIME_DEPENDENCIES [...])

Writing
  file({WRITE | APPEND}  ...)
  file({TOUCH | TOUCH_NOCREATE} [...])
  file(GENERATE OUTPUT  [...])
  file(CONFIGURE OUTPUT  CONTENT  [...])

Filesystem
  file({GLOB | GLOB_RECURSE}  [...] [...])
  file(MAKE_DIRECTORY [...])
  file({REMOVE | REMOVE_RECURSE } [...])
  file(RENAME   [...])
  file(COPY_FILE   [...])
  file({COPY | INSTALL} ... DESTINATION  [...])
  file(SIZE  )
  file(READ_SYMLINK  )
  file(CREATE_LINK   [...])
  file(CHMOD ... ... PERMISSIONS ... [...])
  file(CHMOD_RECURSE ... ... PERMISSIONS ... [...])

Path Conversion
  file(REAL_PATH   [BASE_DIRECTORY ] [EXPAND_TILDE])
  file(RELATIVE_PATH   )
  file({TO_CMAKE_PATH | TO_NATIVE_PATH}  )

Transfer
  file(DOWNLOAD  [] [...])
  file(UPLOAD   [...])

Locking
  file(LOCK  [...])

Archiving
  file(ARCHIVE_CREATE OUTPUT  PATHS ... [...])
  file(ARCHIVE_EXTRACT INPUT  [...])

Reading¶

file(READ  
     [OFFSET ] [LIMIT ] [HEX])

Read content from a file called and store it in a . Optionally start from the given and read at most bytes. The HEX option causes data to be converted to a hexadecimal representation (useful for binary data). If the HEX option is specified, letters in the output (a through f) are in lowercase.

file(STRINGS   [...])

Parse a list of ASCII strings from and store it in . Binary data in the file are ignored. Carriage return (\r, CR) characters are ignored. The options are:

Consider only strings of at most a given length.

Consider only strings of at least a given length.

Limit the number of distinct strings to be extracted.

Limit the number of input bytes to read from the file.

Limit the number of total bytes to store in the .

Treat newline characters (\n, LF) as part of string content instead of terminating at them.

Intel Hex and Motorola S-record files are automatically converted to binary while reading unless this option is given.

Consider only strings that match the given regular expression, as described under string(REGEX).

New in version 3.1.

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.

New in version 3.2: Added the UTF-16LE, UTF-16BE, UTF-32LE, UTF-32BE encodings.

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

Compute a cryptographic hash of the content of and store it in a . The supported algorithm names are those listed by the string() command.

file(TIMESTAMP   [] [UTC])

Compute a string representation of the modification time of and store it in . 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 and UTC options.

file(GET_RUNTIME_DEPENDENCIES
  [RESOLVED_DEPENDENCIES_VAR ]
  [UNRESOLVED_DEPENDENCIES_VAR ]
  [CONFLICTING_DEPENDENCIES_PREFIX ]
  [EXECUTABLES [...]]
  [LIBRARIES [...]]
  [MODULES [...]]
  [DIRECTORIES [...]]
  [BUNDLE_EXECUTABLE ]
  [PRE_INCLUDE_REGEXES [...]]
  [PRE_EXCLUDE_REGEXES [...]]
  [POST_INCLUDE_REGEXES [...]]
  [POST_EXCLUDE_REGEXES [...]]
  [POST_INCLUDE_FILES [...]]
  [POST_EXCLUDE_FILES [...]]
  )

New in version 3.16.

Recursively get the list of libraries depended on by the given files.

Please note that this sub-command is not intended to be used in project mode. It is intended for use at install time, either from code generated by the install(RUNTIME_DEPENDENCY_SET) command, or from code provided by the project via install(CODE) or install(SCRIPT). For example:

install(CODE [[
  file(GET_RUNTIME_DEPENDENCIES
    # ...
    )
  ]])

The arguments are as follows:

Name of the variable in which to store the list of resolved dependencies.

Name of the variable in which to store the list of unresolved dependencies. If this variable is not specified, and there are any unresolved dependencies, an error is issued.

Variable prefix in which to store conflicting dependency information. Dependencies are conflicting if two files with the same name are found in two different directories. The list of filenames that conflict are stored in _FILENAMES. For each filename, the list of paths that were found for that filename are stored in _.

List of executable files to read for dependencies. These are executables that are typically created with add_executable(), but they do not have to be created by CMake. On Apple platforms, the paths to these files determine the value of @executable_path when recursively resolving the libraries. Specifying any kind of library (STATIC, MODULE, or SHARED) here will result in undefined behavior.

List of library files to read for dependencies. These are libraries that are typically created with add_library(SHARED), but they do not have to be created by CMake. Specifying STATIC libraries, MODULE libraries, or executables here will result in undefined behavior.

List of loadable module files to read for dependencies. These are modules that are typically created with add_library(MODULE), but they do not have to be created by CMake. They are typically used by calling dlopen() at runtime rather than linked at link time with ld -l. Specifying STATIC libraries, SHARED libraries, or executables here will result in undefined behavior.

List of additional directories to search for dependencies. On Linux platforms, these directories are searched if the dependency is not found in any of the other usual paths. If it is found in such a directory, a warning is issued, because it means that the file is incomplete (it does not list all of the directories that contain its dependencies). On Windows platforms, these directories are searched if the dependency is not found in any of the other search paths, but no warning is issued, because searching other paths is a normal part of Windows dependency resolution. On Apple platforms, this argument has no effect.

Executable to treat as the "bundle executable" when resolving libraries. On Apple platforms, this argument determines the value of @executable_path when recursively resolving libraries for LIBRARIES and MODULES files. It has no effect on EXECUTABLES files. On other platforms, it has no effect. This is typically (but not always) one of the executables in the EXECUTABLES argument which designates the "main" executable of the package.

The following arguments specify filters for including or excluding libraries to be resolved. See below for a full description of how they work.

List of pre-include regexes through which to filter the names of not-yet-resolved dependencies.

List of pre-exclude regexes through which to filter the names of not-yet-resolved dependencies.

List of post-include regexes through which to filter the names of resolved dependencies.

List of post-exclude regexes through which to filter the names of resolved dependencies.

New in version 3.21.

List of post-include filenames through which to filter the names of resolved dependencies. Symlinks are resolved when attempting to match these filenames.

New in version 3.21.

List of post-exclude filenames through which to filter the names of resolved dependencies. Symlinks are resolved when attempting to match these filenames.

These arguments can be used to exclude unwanted system libraries when resolving the dependencies, or to include libraries from a specific directory. The filtering works as follows:

1. If the not-yet-resolved dependency matches any of the PRE_INCLUDE_REGEXES, steps 2 and 3 are skipped, and the dependency resolution proceeds to step 4.

2. If the not-yet-resolved dependency matches any of the PRE_EXCLUDE_REGEXES, dependency resolution stops for that dependency.

3. Otherwise, dependency resolution proceeds.

4. file(GET_RUNTIME_DEPENDENCIES) searches for the dependency according to the linking rules of the platform (see below).

5. If the dependency is found, and its full path matches one of the POST_INCLUDE_REGEXES or POST_INCLUDE_FILES, the full path is added to the resolved dependencies, and file(GET_RUNTIME_DEPENDENCIES) recursively resolves that library's own dependencies. Otherwise, resolution proceeds to step 6.

6. If the dependency is found, but its full path matches one of the POST_EXCLUDE_REGEXES or POST_EXCLUDE_FILES, it is not added to the resolved dependencies, and dependency resolution stops for that dependency.

7. If the dependency is found, and its full path does not match either POST_INCLUDE_REGEXES, POST_INCLUDE_FILES, POST_EXCLUDE_REGEXES, or POST_EXCLUDE_FILES, the full path is added to the resolved dependencies, and file(GET_RUNTIME_DEPENDENCIES) recursively resolves that library's own dependencies.

Different platforms have different rules for how dependencies are resolved. These specifics are described here.

On Linux platforms, library resolution works as follows:

1. If the depending file does not have any RUNPATH entries, and the library exists in one of the depending file's RPATH entries, or its parents', in that order, the dependency is resolved to that file.

2. Otherwise, if the depending file has any RUNPATH entries, and the library exists in one of those entries, the dependency is resolved to that file.

3. Otherwise, if the library exists in one of the directories listed by ldconfig, the dependency is resolved to that file.

4. Otherwise, if the library exists in one of the DIRECTORIES entries, the dependency is resolved to that file. In this case, a warning is issued, because finding a file in one of the DIRECTORIES means that the depending file is not complete (it does not list all the directories from which it pulls dependencies).

5. Otherwise, the dependency is unresolved.

On Windows platforms, library resolution works as follows:

1. The dependent DLL name is converted to lowercase. Windows DLL names are case-insensitive, and some linkers mangle the case of the DLL dependency names. However, this makes it more difficult for PRE_INCLUDE_REGEXES, PRE_EXCLUDE_REGEXES, POST_INCLUDE_REGEXES, and POST_EXCLUDE_REGEXES to properly filter DLL names - every regex would have to check for both uppercase and lowercase letters. For example:

   file(GET_RUNTIME_DEPENDENCIES
     # ...
     PRE_INCLUDE_REGEXES "^[Mm][Yy][Ll][Ii][Bb][Rr][Aa][Rr][Yy]\\.[Dd][Ll][Ll]$"
     )
   

   Converting the DLL name to lowercase allows the regexes to only match lowercase names, thus simplifying the regex. For example:

   file(GET_RUNTIME_DEPENDENCIES
     # ...
     PRE_INCLUDE_REGEXES "^mylibrary\\.dll$"
     )
   

   This regex will match mylibrary.dll regardless of how it is cased, either on disk or in the depending file. (For example, it will match mylibrary.dll, MyLibrary.dll, and MYLIBRARY.DLL.)

   Please note that the directory portion of any resolved DLLs retains its casing and is not converted to lowercase. Only the filename portion is converted.

2. (Not yet implemented) If the depending file is a Windows Store app, and the dependency is listed as a dependency in the application's package manifest, the dependency is resolved to that file.

3. Otherwise, if the library exists in the same directory as the depending file, the dependency is resolved to that file.

4. Otherwise, if the library exists in either the operating system's system32 directory or the Windows directory, in that order, the dependency is resolved to that file.

5. Otherwise, if the library exists in one of the directories specified by DIRECTORIES, in the order they are listed, the dependency is resolved to that file. In this case, a warning is not issued, because searching other directories is a normal part of Windows library resolution.

6. Otherwise, the dependency is unresolved.

On Apple platforms, library resolution works as follows:

1. If the dependency starts with @executable_path/, and an EXECUTABLES argument is in the process of being resolved, and replacing @executable_path/ with the directory of the executable yields an existing file, the dependency is resolved to that file.

2. Otherwise, if the dependency starts with @executable_path/, and there is a BUNDLE_EXECUTABLE argument, and replacing @executable_path/ with the directory of the bundle executable yields an existing file, the dependency is resolved to that file.

3. Otherwise, if the dependency starts with @loader_path/, and replacing @loader_path/ with the directory of the depending file yields an existing file, the dependency is resolved to that file.

4. Otherwise, if the dependency starts with @rpath/, and replacing @rpath/ with one of the RPATH entries of the depending file yields an existing file, the dependency is resolved to that file. Note that RPATH entries that start with @executable_path/ or @loader_path/ also have these items replaced with the appropriate path.

5. Otherwise, if the dependency is an absolute file that exists, the dependency is resolved to that file.

6. Otherwise, the dependency is unresolved.

This function accepts several variables that determine which tool is used for dependency resolution:

Determines which operating system and executable format the files are built for. This could be one of several values:

• linux+elf

• windows+pe

• macos+macho

If this variable is not specified, it is determined automatically by system introspection.

Determines the tool to use for dependency resolution. It could be one of several values, depending on the value of CMAKE_GET_RUNTIME_DEPENDENCIES_PLATFORM:

If this variable is not specified, it is determined automatically by system introspection.

Determines the path to the tool to use for dependency resolution. This is the actual path to objdump, dumpbin, or otool.

If this variable is not specified, it is determined by the value of CMAKE_OBJDUMP if set, else by system introspection.

New in version 3.18: Use CMAKE_OBJDUMP if set.

Writing¶

file(WRITE  ...)
file(APPEND  ...)

Write into a file called . 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 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 [...])
file(TOUCH_NOCREATE [...])

New in version 3.12.

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] [TARGET target]
     [NO_SOURCE_PERMISSIONS | USE_SOURCE_PERMISSIONS |
      FILE_PERMISSIONS ...]
     [NEWLINE_STYLE [UNIX|DOS|WIN32|LF|CRLF] ])

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:

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.

Use the content given explicitly as input.

Use the content from a given file as input.

Changed in version 3.10: A relative path is treated with respect to the value of CMAKE_CURRENT_SOURCE_DIR. See policy CMP0070.

Specify the output file name to generate. Use generator expressions such as $ 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 must evaluate to an unique name for each configuration.

Changed in version 3.10: A relative path (after evaluating generator expressions) is treated with respect to the value of CMAKE_CURRENT_BINARY_DIR. See policy CMP0070.

New in version 3.19.

Specify which target to use when evaluating generator expressions that require a target for evaluation (e.g. $, $).

New in version 3.20.

The generated file permissions default to the standard 644 value (-rw-r--r--).

New in version 3.20.

Transfer the file permissions of the INPUT file to the generated file. This is already the default behavior if none of the three permissions-related keywords are given (NO_SOURCE_PERMISSIONS, USE_SOURCE_PERMISSIONS or FILE_PERMISSIONS). The USE_SOURCE_PERMISSIONS keyword mostly serves as a way of making the intended behavior clearer at the call site. It is an error to specify this option without INPUT.

New in version 3.20.

Use the specified permissions for the generated file.