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 Generator 支持的每个构建配置生成一个输出文件。从输入内容评估 生成器表达式 以生成输出内容。

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> 中。通配符表达式类似于正则表达式，但更简单。如果指定了 RELATIVE 标志，结果将作为相对于给定路径的相对路径返回。

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

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

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 上有意义，因为文件创建后可能会在短时间内无法访问。使用此选项，如果权限被拒绝，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> 是 ~ 或以 ~/ 开头，则 ~ 将替换为用户的主目录。主目录的路径从环境变量中获取。在 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 文件的替代文件。如果未指定此选项，则将使用 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 版本中的变更： 默认值为 on。以前，默认值为 off。用户可以将 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 中新增。

如果不存在 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>] [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>

在解析库时，要视为“捆绑可执行文件”的可执行文件。在 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 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，则使用它。