file

文件操作命令。

此命令专用于需要访问文件系统的文件和路径操作。

对于其他仅处理语法方面的路径操作，请查看 cmake_path() 命令。

注意

子命令 RELATIVE_PATH、TO_CMAKE_PATH 和 TO_NATIVE_PATH 已分别被 cmake_path() 命令的子命令 RELATIVE_PATH、CONVERT ... TO_CMAKE_PATH_LIST 和 CONVERT ... TO_NATIVE_PATH_LIST 所取代。

概要

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> [...])
  file(CONFIGURE OUTPUT <output-file> CONTENT <content> [...])

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

Path Conversion
  file(REAL_PATH <path> <out-var> [BASE_DIRECTORY <dir>] [EXPAND_TILDE])
  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> [...])

Archiving
  file(ARCHIVE_CREATE OUTPUT <archive> PATHS <paths>... [...])
  file(ARCHIVE_EXTRACT INPUT <archive> [...])

Handling Runtime Binaries
  file(GET_RUNTIME_DEPENDENCIES [...])

读取

file(READ <filename> <variable> [OFFSET <offset>] [LIMIT <max-in>] [HEX])

从名为 <filename> 的文件中读取内容，并将其存储在 <variable> 中。可以选择从给定的 <offset> 开始，最多读取 <max-in> 个字节。HEX 选项使数据转换为十六进制表示形式（对于二进制数据很有用）。如果指定了 HEX 选项，则输出中的字母（a 到 f）将为小写。

file(STRINGS <filename> <variable> <options>...)

从 <filename> 中解析 ASCII 字符串列表，并将其存储在 <variable> 中。文件中的二进制数据将被忽略。回车符（\r，CR）将被忽略。选项包括：

LENGTH_MAXIMUM <max-len>

仅考虑长度不超过给定长度的字符串。

LENGTH_MINIMUM <min-len>

仅考虑长度至少为给定长度的字符串。

LIMIT_COUNT <max-num>

限制要提取的不同字符串的数量。

LIMIT_INPUT <max-in>

限制从文件中读取的输入字节数。

LIMIT_OUTPUT <max-out>

限制要存储在 <variable> 中的总字节数。

NEWLINE_CONSUME

将换行符（\n，LF）视为字符串内容的一部分，而不是在其处终止。

NO_HEX_CONVERSION

除非给定此选项，否则 Intel Hex 和 Motorola S-record 文件在读取时会自动转换为二进制文件。

REGEX <regex>

仅考虑与给定正则表达式匹配的字符串，如 string(REGEX) 中所述。

在 3.29 版本中变更: 文件中最后一个匹配项的捕获组存储在 CMAKE_MATCH_<n> 中，类似于 string(REGEX MATCHALL)。请参阅策略 CMP0159。

ENCODING <encoding-type>

在 3.1 版本中添加。

考虑给定编码的字符串。当前支持的编码有：UTF-8、UTF-16LE、UTF-16BE、UTF-32LE、UTF-32BE。如果未提供 ENCODING 选项，并且文件具有字节顺序标记，则 ENCODING 选项将默认为遵守字节顺序标记。

在 3.2 版本中添加: 添加了 UTF-16LE、UTF-16BE、UTF-32LE、UTF-32BE 编码。

例如，以下代码

file(STRINGS myfile.txt myfile)

在变量 myfile 中存储一个列表，其中每个项目都是输入文件中的一行。

file(<HASH> <filename> <variable>)

计算 <filename> 内容的加密哈希值，并将其存储在 <variable> 中。支持的 <HASH> 算法名称是 string(<HASH>) 命令列出的名称。

file(TIMESTAMP <filename> <variable> [<format>] [UTC])

计算 <filename> 修改时间的字符串表示形式，并将其存储在 <variable> 中。如果命令无法获取时间戳，则变量将设置为空字符串（""）。

有关 <format> 和 UTC 选项的文档，请参阅 string(TIMESTAMP) 命令。

写入

file(WRITE <filename> <content>...)

file(APPEND <filename> <content>...)

将 <content> 写入名为 <filename> 的文件。如果该文件不存在，则会创建它。如果该文件已存在，WRITE 模式将覆盖它，而 APPEND 模式将追加到末尾。由 <filename> 指定的路径中任何不存在的目录都将被创建。

如果该文件是构建输入，请使用 configure_file() 命令，以便仅在该文件内容更改时才更新该文件。

file(TOUCH <files>...)

file(TOUCH_NOCREATE <files>...)

在 3.12 版本中添加。

创建一个没有内容的文件（如果该文件尚不存在）。如果该文件已存在，则其访问和/或修改时间将更新为函数调用执行的时间。

使用 TOUCH_NOCREATE 在文件存在时触摸它，但不创建它。如果文件不存在，它将被静默忽略。

使用 TOUCH 和 TOUCH_NOCREATE，现有文件的内容将不会被修改。

在 3.30 版本中变更: <files> 可以是空列表。CMake 3.29 及更早版本要求至少提供一个文件。

file(GENERATE [...])

为当前 CMake 生成器 支持的每个构建配置生成一个输出文件。从输入内容评估 生成器表达式 以生成输出内容。

file(GENERATE OUTPUT <output-file>
     <INPUT <input-file>|CONTENT <content>>
     [CONDITION <expression>] [TARGET <target>]
     [NO_SOURCE_PERMISSIONS | USE_SOURCE_PERMISSIONS |
      FILE_PERMISSIONS <permissions>...]
     [NEWLINE_STYLE [UNIX|DOS|WIN32|LF|CRLF]])

选项包括：

CONDITION <condition>

仅当条件为真时，才为特定配置生成输出文件。条件在评估生成器表达式后必须为 0 或 1。

CONTENT <content>

使用显式给定的内容作为输入。

INPUT <input-file>

使用给定文件的内容作为输入。

在 3.10 版本中变更: 相对路径相对于 CMAKE_CURRENT_SOURCE_DIR 的值进行处理。请参阅策略 CMP0070。

OUTPUT <output-file>

指定要生成的输出文件名。使用生成器表达式，例如 $<CONFIG>，以指定特定于配置的输出文件名。仅当生成的内容相同时，多个配置才可以生成相同的输出文件。否则，<output-file> 必须为每个配置评估为唯一的名称。

在 3.10 版本中变更: 相对路径（在评估生成器表达式后）相对于 CMAKE_CURRENT_BINARY_DIR 的值进行处理。请参阅策略 CMP0070。

TARGET <target>

在 3.19 版本中添加。

指定在评估需要目标进行评估的生成器表达式时要使用的目标（例如 $<COMPILE_FEATURES:...>, $<TARGET_PROPERTY:prop>）。

NO_SOURCE_PERMISSIONS

在 3.20 版本中添加。

生成的文件权限默认为标准 644 值 (-rw-r--r--)。

USE_SOURCE_PERMISSIONS

在 3.20 版本中添加。

将 INPUT 文件的文件权限转移到生成的文件。如果未给出三个权限相关关键字（NO_SOURCE_PERMISSIONS、USE_SOURCE_PERMISSIONS 或 FILE_PERMISSIONS）中的任何一个，则这已经是默认行为。USE_SOURCE_PERMISSIONS 关键字主要用于使调用站点的预期行为更清晰。在没有 INPUT 的情况下指定此选项是错误的。

FILE_PERMISSIONS <permissions>...

在 3.20 版本中添加。

对生成的文件使用指定的权限。

NEWLINE_STYLE <style>

在 3.20 版本中添加。

指定生成文件的换行符样式。指定 UNIX 或 LF 表示 \n 换行符，或指定 DOS、WIN32 或 CRLF 表示 \r\n 换行符。

必须给出恰好一个 CONTENT 或 INPUT 选项。一个特定的 OUTPUT 文件最多可以由一个 file(GENERATE) 调用命名。仅当生成文件的内容发生更改时，才会在后续的 cmake 运行中修改生成的文件并更新其时间戳。

另请注意，file(GENERATE) 在生成阶段之前不会创建输出文件。当 file(GENERATE) 命令返回时，输出文件尚未写入，它仅在处理完项目的所有 CMakeLists.txt 文件后才写入。

file(CONFIGURE OUTPUT <output-file> CONTENT <content> [ESCAPE_QUOTES] [@ONLY] [NEWLINE_STYLE [UNIX|DOS|WIN32|LF|CRLF]])

在 3.18 版本中添加。

使用 CONTENT 给定的输入生成输出文件，并替换其中引用的变量值，形式为 @VAR@ 或 ${VAR}。替换规则的行为与 configure_file() 命令相同。为了匹配 configure_file() 的行为，OUTPUT 和 CONTENT 都不支持生成器表达式，并且仅当内容更改或文件之前不存在时，才会修改输出文件并更新其时间戳。

参数包括：

OUTPUT <output-file>

指定要生成的输出文件名。相对路径相对于 CMAKE_CURRENT_BINARY_DIR 的值进行处理。<output-file> 不支持生成器表达式。

CONTENT <content>

使用显式给定的内容作为输入。<content> 不支持生成器表达式。

ESCAPE_QUOTES

使用反斜杠（C 样式）转义任何替换的引号。

@ONLY

将变量替换限制为 @VAR@ 形式的引用。这对于配置使用 ${VAR} 语法的脚本很有用。

NEWLINE_STYLE <style>

指定输出文件的换行符样式。指定 UNIX 或 LF 表示 \n 换行符，或指定 DOS、WIN32 或 CRLF 表示 \r\n 换行符。

文件系统

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

生成与 <globbing-expressions> 匹配的文件列表，并将其存储到 <variable> 中。Globbing 表达式类似于正则表达式，但要简单得多。如果指定了 RELATIVE 标志，则结果将作为相对于给定路径的相对路径返回。

在 3.6 版本中变更: 结果将按字典顺序排序。

在 Windows 和 macOS 上，即使底层文件系统区分大小写，globbing 也不区分大小写（文件名和 globbing 表达式在匹配之前都转换为小写）。在其他平台上，globbing 区分大小写。

在 3.3 版本中添加: 默认情况下，GLOB 列出目录。如果 LIST_DIRECTORIES 设置为 false，则目录将从结果中省略。

在 3.12 版本中添加: 如果指定了 CONFIGURE_DEPENDS 标志，CMake 将向主构建系统检查目标添加逻辑，以在构建时重新运行标记的 GLOB 命令。如果任何输出发生更改，CMake 将重新生成构建系统。

注意

我们不建议使用 GLOB 从源代码树中收集源文件列表。如果在添加或删除源文件时没有 CMakeLists.txt 文件更改，则生成的构建系统无法知道何时要求 CMake 重新生成。CONFIGURE_DEPENDS 标志可能无法在所有生成器上可靠地工作，或者如果将来添加了不支持它的新生成器，则使用它的项目将陷入困境。即使 CONFIGURE_DEPENDS 可靠地工作，每次重建时执行检查仍然会产生开销。

globbing 表达式的示例包括：

*.cxx	匹配所有扩展名为 cxx 的文件
*.vt?	匹配所有扩展名为 vta, ..., vtz 的文件
f[3-5].txt	匹配文件 f3.txt, f4.txt, f5.txt

GLOB_RECURSE 模式将遍历匹配目录的所有子目录并匹配文件。仅当给定 FOLLOW_SYMLINKS 或策略 CMP0009 未设置为 NEW 时，才会遍历作为符号链接的子目录。

在 3.3 版本中添加: 默认情况下，GLOB_RECURSE 从结果列表中省略目录。将 LIST_DIRECTORIES 设置为 true 会将目录添加到结果列表中。如果给定 FOLLOW_SYMLINKS 或策略 CMP0009 未设置为 NEW，则 LIST_DIRECTORIES 将符号链接视为目录。

递归 globbing 的示例包括：

/dir/*.py

匹配 /dir 和子目录中的所有 python 文件

file(MAKE_DIRECTORY <directories>... [RESULT <result>])

根据需要创建给定的目录及其父目录。相对输入路径是相对于当前源目录评估的。

选项包括：

RESULT <result>

在 3.31 版本中添加。

成功时将 <result> 变量设置为 0，否则设置为错误消息。如果未指定 RESULT 并且操作失败，则会发出错误。

在 3.30 版本中变更: <directories> 可以是空列表。CMake 3.29 及更早版本要求至少提供一个目录。

file(REMOVE <files>...)

file(REMOVE_RECURSE <files>...)

删除给定的文件。REMOVE_RECURSE 模式将删除给定的文件和目录，包括非空目录。如果给定的文件不存在，则不会发出错误。相对输入路径是相对于当前源目录评估的。

在 3.15 版本中变更: 空输入路径将被忽略并发出警告。CMake 的早期版本将空字符串解释为相对于当前目录的相对路径，并删除了其内容。

file(RENAME <oldname> <newname> [RESULT <result>] [NO_REPLACE])

在文件系统内将文件或目录从 <oldname> 移动到 <newname>，原子地替换目标位置。

选项包括：

RESULT <result>

在 3.21 版本中添加。

成功时将 <result> 变量设置为 0，否则设置为错误消息。如果未指定 RESULT 并且操作失败，则会发出错误。

NO_REPLACE

在 3.21 版本中添加。

如果 <newname> 路径已存在，则不替换它。如果使用了 RESULT <result>，结果变量将被设置为 NO_REPLACE。否则，将发出错误。

file(COPY_FILE <oldname> <newname> [RESULT <result>] [ONLY_IF_DIFFERENT] [INPUT_MAY_BE_RECENT])

在 3.21 版本中添加。

将文件从 <oldname> 复制到 <newname>。不支持目录。符号链接将被忽略，并且 <oldfile> 的内容将被读取并写入到 <newname> 中作为一个新文件。

选项包括：

RESULT <result>

成功时将 <result> 变量设置为 0，否则设置为错误消息。如果未指定 RESULT 并且操作失败，则会发出错误。

ONLY_IF_DIFFERENT

如果 <newname> 路径已存在，并且该文件的内容与 <oldname> 的内容相同，则不替换它（这避免了更新 <newname> 的时间戳）。

INPUT_MAY_BE_RECENT

在 3.26 版本中添加。

告诉 CMake 输入文件可能是最近创建的。这仅在 Windows 上有意义，在 Windows 上，文件在创建后可能会在短时间内无法访问。使用此选项，如果权限被拒绝，CMake 将重试读取输入文件几次。

此子命令与带有 COPYONLY 选项的 configure_file() 有些相似之处。一个重要的区别是 configure_file() 会创建对源文件的依赖关系，因此如果源文件发生更改，CMake 将重新运行。file(COPY_FILE) 子命令不会创建这种依赖关系。

另请参阅下面的 file(COPY) 子命令，它提供了更进一步的文件复制功能。

file(COPY [...])

file(INSTALL [...])

COPY 签名将文件、目录和符号链接复制到目标文件夹。相对输入路径相对于当前源目录进行评估，而相对目标路径相对于当前构建目录进行评估。复制操作会保留输入文件的时间戳，并且如果目标位置已存在具有相同时间戳的文件，则会优化掉复制操作。复制操作会保留输入权限，除非给定了显式权限或 NO_SOURCE_PERMISSIONS（默认值为 USE_SOURCE_PERMISSIONS）。

file(<COPY|INSTALL> <files>... DESTINATION <dir>
     [NO_SOURCE_PERMISSIONS | USE_SOURCE_PERMISSIONS]
     [FILE_PERMISSIONS <permissions>...]
     [DIRECTORY_PERMISSIONS <permissions>...]
     [FOLLOW_SYMLINK_CHAIN]
     [FILES_MATCHING]
     [[PATTERN <pattern> | REGEX <regex>]
      [EXCLUDE] [PERMISSIONS <permissions>...]] [...])

注意

对于简单的文件复制操作，上面的 file(COPY_FILE) 子命令可能更容易使用。

在 3.15 版本中添加: 如果指定了 FOLLOW_SYMLINK_CHAIN，COPY 将递归地解析给定路径上的符号链接，直到找到真实文件，并在目标位置为遇到的每个符号链接安装相应的符号链接。对于安装的每个符号链接，解析结果都会剥离目录，只留下文件名，这意味着新的符号链接指向与符号链接位于同一目录中的文件。此功能在某些 Unix 系统上很有用，在这些系统中，库以带有版本号的符号链接链的形式安装，不太具体的版本指向更具体的版本。FOLLOW_SYMLINK_CHAIN 将安装所有这些符号链接和库本身到目标目录中。例如，如果您有以下目录结构

• /opt/foo/lib/libfoo.so.1.2.3

• /opt/foo/lib/libfoo.so.1.2 -> libfoo.so.1.2.3

• /opt/foo/lib/libfoo.so.1 -> libfoo.so.1.2

• /opt/foo/lib/libfoo.so -> libfoo.so.1

并且您执行以下操作

file(COPY /opt/foo/lib/libfoo.so DESTINATION lib FOLLOW_SYMLINK_CHAIN)

这将安装所有符号链接和 libfoo.so.1.2.3 本身到 lib 中。

有关权限、FILES_MATCHING、PATTERN、REGEX 和 EXCLUDE 选项的文档，请参阅 install(DIRECTORY) 命令。即使使用选项选择文件子集，复制目录也会保留其内容的结构。

INSTALL 签名与 COPY 略有不同：它会打印状态消息，并且 NO_SOURCE_PERMISSIONS 是默认值。install() 命令生成的安装脚本使用此签名（带有一些未记录的选项供内部使用）。

在 3.22 版本中更改: 环境变量 CMAKE_INSTALL_MODE 可以覆盖 file(INSTALL) 的默认复制行为。

file(SIZE <filename> <variable>)

在 3.14 版本中添加。

确定 <filename> 的文件大小，并将结果放入 <variable> 变量中。要求 <filename> 是指向文件的有效路径并且可读。

file(READ_SYMLINK <linkname> <variable>)

在 3.14 版本中添加。

查询符号链接 <linkname>，并将它指向的路径存储在结果 <variable> 中。如果 <linkname> 不存在或不是符号链接，CMake 将发出致命错误。

请注意，此命令返回原始符号链接路径，并且不解析相对路径。以下是如何确保获得绝对路径的示例

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

在 3.14 版本中添加。

创建指向 <original> 的链接 <linkname>。默认情况下，它将是硬链接，但提供 SYMBOLIC 选项将生成符号链接。硬链接要求 original 存在并且是一个文件，而不是目录。如果 <linkname> 已经存在，它将被覆盖。

如果指定了 <result> 变量，它将接收操作的状态。成功时设置为 0，否则设置为错误消息。如果未指定 RESULT 并且操作失败，则会发出致命错误。

指定 COPY_ON_ERROR 可以在创建链接失败时启用复制文件作为回退。这对于处理诸如 <original> 和 <linkname> 位于不同的驱动器或挂载点之类的情况很有用，这将使它们无法支持硬链接。

file(CHMOD <files>... <directories>... [PERMISSIONS <permissions>...] [FILE_PERMISSIONS <permissions>...] [DIRECTORY_PERMISSIONS <permissions>...])

在 3.19 版本中添加。

设置指定的 <files>... 和 <directories>... 的权限。有效的权限是 OWNER_READ、OWNER_WRITE、OWNER_EXECUTE、GROUP_READ、GROUP_WRITE、GROUP_EXECUTE、WORLD_READ、WORLD_WRITE、WORLD_EXECUTE、SETUID、SETGID。

有效的关键字组合是

PERMISSIONS

所有项目都将更改。

FILE_PERMISSIONS

仅更改文件。

DIRECTORY_PERMISSIONS

仅更改目录。

PERMISSIONS 和 FILE_PERMISSIONS

FILE_PERMISSIONS 覆盖文件的 PERMISSIONS。

PERMISSIONS 和 DIRECTORY_PERMISSIONS

DIRECTORY_PERMISSIONS 覆盖目录的 PERMISSIONS。

FILE_PERMISSIONS 和 DIRECTORY_PERMISSIONS

对文件使用 FILE_PERMISSIONS，对目录使用 DIRECTORY_PERMISSIONS。

file(CHMOD_RECURSE <files>... <directories>... [PERMISSIONS <permissions>...] [FILE_PERMISSIONS <permissions>...] [DIRECTORY_PERMISSIONS <permissions>...])

在 3.19 版本中添加。

与 CHMOD 相同，但递归更改 <directories>... 中存在的文件和目录的权限。

路径转换

file(REAL_PATH <path> <out-var> [BASE_DIRECTORY <dir>] [EXPAND_TILDE])

在 3.19 版本中添加。

计算现有文件或目录的绝对路径，并解析符号链接。选项包括

BASE_DIRECTORY <dir>

如果提供的 <path> 是相对路径，则相对于给定的基本目录 <dir> 进行评估。如果未提供基本目录，则默认基本目录将为 CMAKE_CURRENT_SOURCE_DIR。

EXPAND_TILDE

在 3.21 版本中添加。

如果 <path> 是 ~ 或以 ~/ 开头，则 ~ 将替换为用户的 home 目录。home 目录的路径从环境变量中获取。在 Windows 上，使用 USERPROFILE 环境变量，如果未定义 USERPROFILE，则回退到 HOME 环境变量。在所有其他平台上，仅使用 HOME。

在 3.28 版本中更改: 在折叠 ../ 组件之前解析所有符号链接。请参阅策略 CMP0152。

file(RELATIVE_PATH <variable> <directory> <file>)

计算从 <directory> 到 <file> 的相对路径，并将其存储在 <variable> 中。

file(TO_CMAKE_PATH "<path>" <variable>)

file(TO_NATIVE_PATH "<path>" <variable>)

TO_CMAKE_PATH 模式将本机 <path> 转换为带有正斜杠 (/) 的 CMake 风格路径。输入可以是单个路径，也可以是系统搜索路径，例如 $ENV{PATH}。搜索路径将转换为以 ; 字符分隔的 CMake 风格列表。

TO_NATIVE_PATH 模式将 CMake 风格的 <path> 转换为带有平台特定斜杠的本机路径（Windows 主机上为 \，其他地方为 /）。

始终在 <path> 周围使用双引号，以确保它被视为此命令的单个参数。

传输

file(DOWNLOAD <url> [<file>] <options>...)

file(UPLOAD <file> <url> <options>...)

DOWNLOAD 子命令将给定的 <url> 下载到本地 <file>。UPLOAD 模式将本地 <file> 上传到给定的 <url>。

在 3.19 版本中添加: 如果未为 file(DOWNLOAD) 指定 <file>，则不会保存该文件。如果您想知道是否可以下载文件（例如，检查文件是否存在）而无需实际将其保存到任何地方，这将非常有用。

DOWNLOAD 和 UPLOAD 的选项包括

INACTIVITY_TIMEOUT <seconds>

在不活动一段时间后终止操作。

LOG <variable>

将操作的人工可读日志存储在变量中。

SHOW_PROGRESS

在操作完成之前，以状态消息形式打印进度信息。

STATUS <variable>

将操作的结果状态存储在变量中。状态是以 ; 分隔的长度为 2 的列表。第一个元素是操作的数字返回值，第二个元素是错误的字符串值。数字错误 0 表示操作中没有错误。

TIMEOUT <seconds>

在给定的总时间过后终止操作。

USERPWD <username>:<password>

在 3.7 版本中添加。

设置操作的用户名和密码。

HTTPHEADER <HTTP-header>

在 3.7 版本中添加。

DOWNLOAD 和 UPLOAD 操作的 HTTP 标头。HTTPHEADER 可以重复多次以设置多个选项

file(DOWNLOAD <url>
     HTTPHEADER "Authorization: Bearer <auth-token>"
     HTTPHEADER "UserAgent: Mozilla/5.0")

NETRC <level>

在 3.11 版本中添加。

指定是否为操作使用 .netrc 文件。如果未指定此选项，则将使用 CMAKE_NETRC 变量的值。

有效级别为

IGNORED

.netrc 文件被忽略。这是默认设置。

OPTIONAL

.netrc 文件是可选的，URL 中的信息优先。将扫描该文件以查找 URL 中未指定的信息。

REQUIRED

.netrc 文件是必需的，并且 URL 中的信息将被忽略。

NETRC_FILE <file>

在 3.11 版本中添加。

如果 NETRC 级别为 OPTIONAL 或 REQUIRED，则指定备用 .netrc 文件，而不是您的 home 目录中的文件。如果未指定此选项，则将使用 CMAKE_NETRC_FILE 变量的值。

TLS_VERSION <min>

在 3.30 版本中添加。

为 https:// URL 指定最小 TLS 版本。如果未指定此选项，则将使用 CMAKE_TLS_VERSION 变量或 CMAKE_TLS_VERSION 环境变量的值。有关允许的值，请参阅 CMAKE_TLS_VERSION。

在 3.31 版本中更改: 默认值为 TLS 1.2。以前，默认情况下不强制执行最低版本。

TLS_VERIFY <ON|OFF>

指定是否验证 https:// URL 的服务器证书。如果未指定此选项，则将使用 CMAKE_TLS_VERIFY 变量或 CMAKE_TLS_VERIFY 环境变量的值。如果两者均未设置，则默认值为开启。

版本 3.31 中变更: 默认设置为启用。之前默认设置为禁用。用户可以设置 CMAKE_TLS_VERIFY 环境变量为 0 以恢复旧的默认设置。

版本 3.18 中新增: 添加了对 file(UPLOAD) 的支持。

TLS_CAINFO <file>

为 https:// URL 指定自定义证书颁发机构文件。如果未指定此选项，则将使用 CMAKE_TLS_CAINFO 变量的值。

版本 3.18 中新增: 添加了对 file(UPLOAD) 的支持。

对于 https:// URL，CMake 必须在构建时启用 SSL/TLS 支持。

DOWNLOAD 的附加选项包括

EXPECTED_HASH <algorithm>=<value>

验证下载内容的哈希值是否与预期值匹配，其中 <algorithm> 是 <HASH> 支持的算法之一。如果文件已存在且哈希值匹配，则跳过下载。如果文件已存在但哈希值不匹配，则重新下载该文件。如果在下载后文件哈希值仍不匹配，则操作失败并报错。如果 DOWNLOAD 未提供 <file>，则指定此选项是错误的。

EXPECTED_MD5 <value>

是 EXPECTED_HASH MD5=<value> 的历史简写形式。如果 DOWNLOAD 未提供 <file>，则指定此选项是错误的。

RANGE_START <value>

版本 3.24 中新增。

文件中范围起点的偏移量（以字节为单位）。可以省略此选项以下载到指定的 RANGE_END。

RANGE_END <value>

版本 3.24 中新增。

文件中范围终点的偏移量（以字节为单位）。可以省略此选项以下载从指定的 RANGE_START 到文件末尾的所有内容。

锁定

file(LOCK <path> [DIRECTORY] [RELEASE] [GUARD <FUNCTION|FILE|PROCESS>] [RESULT_VARIABLE <variable>] [TIMEOUT <seconds>])

版本 3.2 中新增。

锁定由 <path> 指定的文件，如果没有 DIRECTORY 选项，则锁定文件 <path>/cmake.lock。文件将被锁定在由 GUARD 选项（默认值为 PROCESS）定义的范围内。RELEASE 选项可用于显式解锁文件。如果未指定 TIMEOUT 选项，CMake 将等待直到锁定成功或发生致命错误。如果 TIMEOUT 设置为 0，将尝试锁定一次，并立即报告结果。如果 TIMEOUT 不为 0，CMake 将尝试在 TIMEOUT <seconds> 值指定的时间段内锁定文件。如果不存在 RESULT_VARIABLE 选项，任何错误都将被解释为致命错误。否则，结果将存储在 <variable> 中，成功时为 0，失败时为错误消息。

请注意，锁定是建议性的；不能保证其他进程会尊重此锁定，即锁定同步共享某些可修改资源的两个或多个 CMake 实例。类似的逻辑适用于 DIRECTORY 选项；锁定父目录不会阻止其他 LOCK 命令锁定任何子目录或文件。

不允许尝试锁定同一文件两次。如果任何中间目录和文件本身不存在，将创建它们。GUARD 和 TIMEOUT 选项在 RELEASE 操作中被忽略。

归档

file(ARCHIVE_CREATE OUTPUT <archive> PATHS <paths>... [FORMAT <format>] [COMPRESSION <compression> [COMPRESSION_LEVEL <compression-level>]] [MTIME <mtime>] [WORKING_DIRECTORY <dir>] [VERBOSE])

在 3.18 版本中添加。

使用 <paths> 中列出的文件和目录创建指定的 <archive> 文件。请注意，<paths> 必须列出实际的文件或目录；不支持通配符。

选项包括：

FORMAT <format>

指定归档格式。<format> 的支持值包括 7zip、gnutar、pax、paxr、raw 和 zip。如果未指定 FORMAT，则默认格式为 paxr。

COMPRESSION <compression>

某些归档格式允许指定压缩类型。7zip 和 zip 归档格式已经隐含了特定的压缩类型。其他格式默认不使用压缩，但可以使用 COMPRESSION 选项指示进行压缩。<compression> 的有效值包括 None、BZip2、GZip、XZ 和 Zstd。

注意

当 FORMAT 设置为 raw 时，只会使用 COMPRESSION 指定的压缩类型压缩一个文件。

COMPRESSION_LEVEL <compression-level>

在 3.19 版本中添加。

可以使用 COMPRESSION_LEVEL 选项指定压缩级别。<compression-level> 应介于 0-9 之间，默认值为 0。当给出 COMPRESSION_LEVEL 时，必须存在 COMPRESSION 选项。

版本 3.26 中新增: Zstd 算法的 <compression-level> 可以设置为 0-19 之间。

MTIME <mtime>

指定 tarball 条目中记录的修改时间。

WORKING_DIRECTORY <dir>

在 3.31 版本中添加。

指定将在其中执行归档创建操作的目录。<paths> 参数中的路径可以相对于此目录。如果未提供此选项，则默认使用当前工作目录。

VERBOSE

启用来自归档操作的详细输出。

file(ARCHIVE_EXTRACT INPUT <archive> [DESTINATION <dir>] [PATTERNS <pattern>...] [LIST_ONLY] [VERBOSE] [TOUCH])

在 3.18 版本中添加。

提取或列出指定的 <archive> 的内容。

选项包括：

DESTINATION <dir>

指定将在其下提取归档内容的目录。如果该目录不存在，则将创建它。如果未指定 DESTINATION，则将使用当前二进制目录。

PATTERNS <pattern>...

仅提取/列出与给定模式之一匹配的文件和目录。支持通配符。如果未给出 PATTERNS 选项，则将列出或提取整个归档。

LIST_ONLY

列出归档中的文件，而不是提取它们。

TOUCH

版本 3.24 中新增。

为提取的文件提供当前的本地时间戳，而不是从归档中提取文件时间戳。

VERBOSE

启用来自提取操作的详细输出。

注意

此子命令的工作目录是 DESTINATION 目录（已提供或已计算），除非指定了 LIST_ONLY。因此，在脚本模式之外，最好为 INPUT 归档提供绝对路径，因为它们不太可能在相对路径有效的位置被提取。

处理运行时二进制文件

file(GET_RUNTIME_DEPENDENCIES [...])

版本 3.16 中新增。

递归获取给定文件所依赖的库列表

file(GET_RUNTIME_DEPENDENCIES
  [RESOLVED_DEPENDENCIES_VAR <deps_var>]
  [UNRESOLVED_DEPENDENCIES_VAR <unresolved_deps_var>]
  [CONFLICTING_DEPENDENCIES_PREFIX <conflicting_deps_prefix>]
  [EXECUTABLES <executable_files>...]
  [LIBRARIES <library_files>...]
  [MODULES <module_files>...]
  [DIRECTORIES <directories>...]
  [BUNDLE_EXECUTABLE <bundle_executable_file>]
  [PRE_INCLUDE_REGEXES <regexes>...]
  [PRE_EXCLUDE_REGEXES <regexes>...]
  [POST_INCLUDE_REGEXES <regexes>...]
  [POST_EXCLUDE_REGEXES <regexes>...]
  [POST_INCLUDE_FILES <files>...]
  [POST_EXCLUDE_FILES <files>...]
  )

请注意，此子命令不适用于在项目模式下使用。它旨在用于安装时，可以来自 install(RUNTIME_DEPENDENCY_SET) 命令生成的代码，也可以来自项目通过 install(CODE) 或 install(SCRIPT) 提供的代码。例如

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

参数如下

RESOLVED_DEPENDENCIES_VAR <deps_var>

用于存储已解析依赖项列表的变量名称。

UNRESOLVED_DEPENDENCIES_VAR <unresolved_deps_var>

用于存储未解析依赖项列表的变量名称。如果未指定此变量，并且存在任何未解析的依赖项，则会发出错误。

CONFLICTING_DEPENDENCIES_PREFIX <conflicting_deps_prefix>

用于存储冲突依赖项信息的前缀变量。如果两个同名文件在两个不同的目录中找到，则依赖项会冲突。冲突的文件名列表存储在 <conflicting_deps_prefix>_FILENAMES 中。对于每个文件名，为该文件名找到的路径列表存储在 <conflicting_deps_prefix>_<filename> 中。

EXECUTABLES <executable_files>...

要读取依赖项的可执行文件列表。这些通常是使用 add_executable() 创建的可执行文件，但它们不一定由 CMake 创建。在 Apple 平台上，这些文件的路径决定了递归解析库时 @executable_path 的值。在此处指定任何类型的库（STATIC、MODULE 或 SHARED）将导致未定义的行为。

LIBRARIES <library_files>...

要读取依赖项的库文件列表。这些通常是使用 add_library(SHARED) 创建的库，但它们不一定由 CMake 创建。在此处指定 STATIC 库、MODULE 库或可执行文件将导致未定义的行为。

MODULES <module_files>...

要读取依赖项的可加载模块文件列表。这些通常是使用 add_library(MODULE) 创建的模块，但它们不一定由 CMake 创建。它们通常在运行时通过调用 dlopen() 使用，而不是在链接时使用 ld -l 链接。在此处指定 STATIC 库、SHARED 库或可执行文件将导致未定义的行为。

DIRECTORIES <directories>...

要搜索依赖项的其他目录列表。在 Linux 平台上，如果在任何其他常用路径中都找不到依赖项，则会搜索这些目录。如果在这样的目录中找到依赖项，则会发出警告，因为这意味着该文件不完整（它没有列出包含其依赖项的所有目录）。在 Windows 平台上，如果在任何其他搜索路径中都找不到依赖项，则会搜索这些目录，但不会发出警告，因为搜索其他路径是 Windows 依赖项解析的正常部分。在 Apple 平台上，此参数无效。

BUNDLE_EXECUTABLE <bundle_executable_file>

在解析库时要视为“bundle 可执行文件”的可执行文件。在 Apple 平台上，此参数决定了递归解析 LIBRARIES 和 MODULES 文件的库时 @executable_path 的值。它对 EXECUTABLES 文件没有影响。在其他平台上，它没有影响。这通常（但不总是）是 EXECUTABLES 参数中的可执行文件之一，用于指定软件包的“主”可执行文件。

以下参数指定用于包含或排除要解析的库的过滤器。请参阅下文以获得关于它们如何工作的完整描述。

PRE_INCLUDE_REGEXES <regexes>...

要通过其过滤尚未解析的依赖项名称的预包含正则表达式列表。

PRE_EXCLUDE_REGEXES <regexes>...

要通过其过滤尚未解析的依赖项名称的预排除正则表达式列表。

POST_INCLUDE_REGEXES <regexes>...

要通过其过滤已解析的依赖项名称的后包含正则表达式列表。

POST_EXCLUDE_REGEXES <regexes>...

要通过其过滤已解析的依赖项名称的后排除正则表达式列表。

POST_INCLUDE_FILES <files>...

在 3.21 版本中添加。

要通过其过滤已解析的依赖项名称的后包含文件名列表。尝试匹配这些文件名时，将解析符号链接。

POST_EXCLUDE_FILES <files>...

在 3.21 版本中添加。

要通过其过滤已解析的依赖项名称的后排除文件名列表。尝试匹配这些文件名时，将解析符号链接。

这些参数可用于在解析依赖项时排除不需要的系统库，或包含来自特定目录的库。过滤工作原理如下

1. 如果尚未解析的依赖项与任何 PRE_INCLUDE_REGEXES 匹配，则跳过步骤 2 和 3，依赖项解析进入步骤 4。

2. 如果尚未解析的依赖项与任何 PRE_EXCLUDE_REGEXES 匹配，则停止该依赖项的依赖项解析。

3. 否则，继续进行依赖项解析。

4. file(GET_RUNTIME_DEPENDENCIES) 根据平台的链接规则搜索依赖项（见下文）。

5. 如果找到依赖项，并且其完整路径与 POST_INCLUDE_REGEXES 或 POST_INCLUDE_FILES 之一匹配，则将完整路径添加到已解析的依赖项中，并且 file(GET_RUNTIME_DEPENDENCIES) 递归解析该库自身的依赖项。否则，解析进入步骤 6。

6. 如果找到依赖项，但其完整路径与 POST_EXCLUDE_REGEXES 或 POST_EXCLUDE_FILES 之一匹配，则不会将其添加到已解析的依赖项中，并且停止该依赖项的依赖项解析。

7. 如果找到依赖项，并且其完整路径与 POST_INCLUDE_REGEXES、POST_INCLUDE_FILES、POST_EXCLUDE_REGEXES 或 POST_EXCLUDE_FILES 都不匹配，则将完整路径添加到已解析的依赖项中，并且 file(GET_RUNTIME_DEPENDENCIES) 递归解析该库自身的依赖项。

不同的平台有不同的依赖项解析规则。这些细节在此处描述。

在 Linux 平台上，库解析的工作方式如下

1. 如果依赖文件没有任何 RUNPATH 条目，并且库存在于依赖文件的 RPATH 条目之一或其父目录中（按此顺序），则依赖项解析为该文件。

2. 否则，如果依赖文件有任何 RUNPATH 条目，并且库存在于这些条目之一中，则依赖项解析为该文件。

3. 否则，如果库存在于 ldconfig 列出的目录之一中，则依赖项解析为该文件。

4. 否则，如果库存在于 DIRECTORIES 条目之一中，则依赖项解析为该文件。在这种情况下，会发出警告，因为在 DIRECTORIES 之一中找到文件意味着依赖文件不完整（它没有列出从中拉取依赖项的所有目录）。

5. 否则，依赖项无法解析。

版本 3.31 中变更: 在处理给定的根 ELF 文件（可执行文件或共享对象）时，对每个遇到的库文件名最多只进行一次解析。如果在依赖树中再次遇到库文件名，则假定为原始解析。此行为更接近 Linux 上动态加载器的行为。

在 Windows 平台上，库解析的工作方式如下

1. DLL 依赖项名称转换为小写以匹配过滤器。Windows DLL 名称不区分大小写，并且某些链接器会混淆 DLL 依赖项名称的大小写。然而，这使得 PRE_INCLUDE_REGEXES、PRE_EXCLUDE_REGEXES、POST_INCLUDE_REGEXES 和 POST_EXCLUDE_REGEXES 更难正确地过滤 DLL 名称 - 每个正则表达式都必须检查大写和小写字母。例如

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

   将 DLL 名称转换为小写允许正则表达式仅匹配小写名称，从而简化正则表达式。例如

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

   此正则表达式将匹配 mylibrary.dll，无论它在磁盘上或在依赖文件中如何区分大小写。（例如，它将匹配 mylibrary.dll、MyLibrary.dll 和 MYLIBRARY.DLL。）

   版本 3.27 中变更: 转换为小写仅在匹配过滤器时适用。过滤后报告的结果会保留每个 DLL 名称的大小写，如果已解析，则保留在磁盘上找到的名称的大小写，否则保留依赖二进制文件引用的名称的大小写。

   在 CMake 3.27 之前，结果以小写 DLL 文件名报告，但目录部分保留其大小写。

2. （**尚未实现**）如果依赖文件是 Windows 应用商店应用，并且依赖项在应用程序的程序包清单中列为依赖项，则依赖项解析为该文件。

3. 否则，如果库与依赖文件位于同一目录中，则依赖项解析为该文件。

4. 否则，如果库存在于操作系统的 system32 目录或 Windows 目录中（按此顺序），则依赖项解析为该文件。

5. 否则，如果库存在于 DIRECTORIES 指定的目录之一中（按它们列出的顺序），则依赖项解析为该文件。在这种情况下，不会发出警告，因为搜索其他目录是 Windows 库解析的正常部分。

6. 否则，依赖项无法解析。

在 Apple 平台上，库解析的工作方式如下

1. 如果依赖项以 @executable_path/ 开头，并且 EXECUTABLES 参数正在解析过程中，并且将 @executable_path/ 替换为可执行文件的目录会产生一个现有文件，则依赖项解析为该文件。

2. 否则，如果依赖项以 @executable_path/ 开头，并且存在 BUNDLE_EXECUTABLE 参数，并且将 @executable_path/ 替换为 bundle 可执行文件的目录会产生一个现有文件，则该依赖项将解析为该文件。

3. 否则，如果依赖项以 @loader_path/ 开头，并且将 @loader_path/ 替换为依赖文件目录会产生一个现有文件，则该依赖项将解析为该文件。

4. 否则，如果依赖项以 @rpath/ 开头，并且将 @rpath/ 替换为依赖文件的 RPATH 条目之一会产生一个现有文件，则该依赖项将解析为该文件。 请注意，以 @executable_path/ 或 @loader_path/ 开头的 RPATH 条目也会将这些项替换为相应的路径。

5. 否则，如果依赖项是存在的绝对文件，则该依赖项将解析为该文件。

6. 否则，依赖项无法解析。

此函数接受多个变量，这些变量确定用于依赖项解析的工具

CMAKE_GET_RUNTIME_DEPENDENCIES_PLATFORM

确定为哪些操作系统和可执行文件格式构建文件。 这可能是以下几个值之一

• linux+elf

• windows+pe

• macos+macho

如果未指定此变量，则会自动通过系统自检确定。

CMAKE_GET_RUNTIME_DEPENDENCIES_TOOL

确定用于依赖项解析的工具。 根据 CMAKE_GET_RUNTIME_DEPENDENCIES_PLATFORM 的值，它可能是以下几个值之一

CMAKE_GET_RUNTIME_DEPENDENCIES_PLATFORM	CMAKE_GET_RUNTIME_DEPENDENCIES_TOOL
linux+elf	objdump
windows+pe	objdump 或 dumpbin
macos+macho	otool

如果未指定此变量，则会自动通过系统自检确定。

CMAKE_GET_RUNTIME_DEPENDENCIES_COMMAND

确定用于依赖项解析的工具的路径。 这是 objdump、 dumpbin 或 otool 的实际路径。

如果未指定此变量，则如果设置了 CMAKE_OBJDUMP 变量，则通过该变量的值确定，否则通过系统自检确定。

3.18 版本新增: 如果设置了 CMAKE_OBJDUMP，则使用它。