file

文件操作命令。

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

对于仅涉及语法层面的其他路径操作，请参阅 cmake_path() 命令。

注意

子命令 file(RELATIVE_PATH)、file(TO_CMAKE_PATH) 和 file(TO_NATIVE_PATH) 已分别被子命令 cmake_path(RELATIVE_PATH)、cmake_path(CONVERT ... TO_CMAKE_PATH_LIST) 和 cmake_path(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 选项且文件具有字节顺序标记（BOM），则 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 版本中添加。

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

必须提供且仅能提供一个 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>

为输出文件指定换行符样式。对于 \n 换行符，指定 UNIX 或 LF；对于 \r\n 换行符，指定 DOS、WIN32 或 CRLF。

文件系统

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> 中。Glob 表达式类似于正则表达式，但要简单得多。如果指定了 RELATIVE 标志，结果将以相对于给定路径的路径返回。

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

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

3.3 版本新增: 默认情况下 GLOB 会列出目录。如果 LIST_DIRECTORIES 设置为 false，结果中将省略目录。

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

注意

我们不建议使用 GLOB 从源树中收集源文件列表。如果添加或删除源文件时 CMakeLists.txt 文件没有发生更改，则生成的构建系统无法知道何时要求 CMake 重新生成。对于某些生成器，CONFIGURE_DEPENDS 标志可能无法可靠工作，或者如果将来添加了不支持此功能的新生成器，使用它的项目将会受阻。即使 CONFIGURE_DEPENDS 能可靠工作，每次重新构建时进行检查也会产生性能成本。

通配符表达式的示例包括

*.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 将符号链接视为目录。

递归通配符的示例包括

/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> 位于不同驱动器或挂载点的情况很有用，因为这种情况不支持硬链接。如果源是目录，如果目标目录不存在，将会创建目标目录。除非策略 CMP0205 未设置为 NEW，否则源目录的内容将被复制到目标目录。

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> 是 ~ 或以 ~/ 开头，则 ~ 将被替换为用户的主目录。主目录的路径通过环境变量获得。在 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} 这样的系统搜索路径。搜索路径将被转换为 分号分隔的列表。

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

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>

3.11 版本新增。

如果 NETRC 级别为 OPTIONAL 或 REQUIRED，请指定一个替代于主目录中默认文件的 .netrc 文件。如果未指定此选项，将改用 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 环境变量的值。如果两者都未设置，则默认为 on。

版本 3.31 中已更改： 默认值为开启。先前，默认值为关闭。用户可以通过设置 CMAKE_TLS_VERIFY 环境变量为 0 来恢复旧的默认值。

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

TLS_CAINFO <file>

为 https:// URL 指定自定义证书颁发机构（CA）文件。如果未指定此选项，将改用 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 中新增。

如果不存在 DIRECTORY 选项，则锁定由 <path> 指定的文件；否则锁定文件 <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>] [THREADS <number>] [WORKING_DIRECTORY <dir>] [VERBOSE])

在 3.18 版本中新增。

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

选项包括

FORMAT <format>

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

默认压缩方法取决于格式

• 7zip 使用 LZMA 压缩

• zip 使用 Deflate 压缩

• 其他格式默认不进行压缩

COMPRESSION <compression>

某些归档格式允许指定压缩类型。7zip 和 zip 归档格式已隐含了特定的压缩类型。其他格式默认不进行压缩，但可以通过 COMPRESSION 选项指定。有效的 <compression> 值为

• 无

• BZip2

• Deflate

  Added in version 4.3.

  这是 GZip 的别名。

• GZip

• LZMA

  Added in version 4.3.

• LZMA2

  Added in version 4.3.

  这是 XZ 的别名。

• PPMd

  Added in version 4.3.

  此压缩方法仅由 7zip 归档格式支持。

• XZ

• Zstd

注意

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

4.3 版本新增：7zip 和 zip 格式支持更改默认压缩方式。

COMPRESSION_LEVEL <compression-level>

3.19 版本新增。

可以通过 COMPRESSION_LEVEL 选项指定压缩级别。<compression-level> 应在 0-9 之间，默认值为 0。当提供 COMPRESSION_LEVEL 时，必须同时存在 COMPRESSION 选项。

值 0 用于指定默认压缩级别。它由归档库后端自动选择，而不是直接由 CMake 本身设置。默认压缩级别可能因归档格式、平台等而异。

3.26 版本新增：Zstd 算法的 <compression-level> 可设置为 0-19。

4.3 版本新增：<compression-level> 现在也可以为 7zip 和 zip 格式指定。Zstd 算法的压缩级别可设置为 0-19（zip 格式除外）。

MTIME <mtime>

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

THREADS <number>

Added in version 4.3.

使用 <number> 个线程来操作归档。

如果设置为 0，将使用机器上可用的核心数。请注意，并非所有压缩模式在所有环境下都支持多线程。

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

启用解压操作的详细输出。

4.3 版本变更：包含路径遍历序列（..）或绝对路径的归档条目出于安全考虑会被拒绝。

注意

此子命令的工作目录是 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>

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

以下参数用于指定包含或排除要解析的库的过滤器。有关其工作原理的完整描述，请参见下文。除非策略 CMP0207 未设置为 NEW，否则文件路径中的目录分隔符可以使用正斜杠进行匹配。

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 Store 应用，且依赖项已在应用程序的包清单中列为依赖项，则依赖项解析为该文件。

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

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

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

6. 否则，依赖项未解析。

在 Apple 平台上，库解析工作原理如下：

1. 如果依赖项以 @executable_path/ 开头，且正在解析 EXECUTABLES 参数，且将 @executable_path/ 替换为可执行文件目录后生成了现有文件，则依赖项解析为该文件。

2. 否则，如果依赖项以 @executable_path/ 开头，且存在 BUNDLE_EXECUTABLE 参数，且将 @executable_path/ 替换为包可执行文件目录后生成了现有文件，则依赖项解析为该文件。

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。