file

文件操作命令。

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

有关其他仅处理语法方面的路径操作，请参阅 cmake_path() 命令。

注意

子命令 RELATIVE_PATH、TO_CMAKE_PATH 和 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 选项且文件有字节顺序标记（Byte Order Mark），则 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 支持的每个构建配置生成一个输出文件。从输入内容中评估 generator expressions 来生成输出内容。

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>（例如 $<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) 调用命名。如果生成的内容相同，多个配置可以生成相同的输出文件；否则，<output-file> 对于每个配置都必须评估为一个唯一的名称。生成的文件的内容如果发生更改，并且时间戳更新，才会响应后续的 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> 中。通配符表达式类似于正则表达式，但简单得多。如果指定了 RELATIVE 标志，结果将以相对于给定路径 <path> 的路径形式返回。

版本 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 将重试读取输入几次。

此子命令与 configure_file() 的 COPYONLY 选项有一些相似之处。一个重要的区别是 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 -> libfoo.so.1.2.3

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

• /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 目录。

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

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 文件，而不是您家目录中的文件，前提是 NETRC 级别为 OPTIONAL 或 REQUIRED。如果未指定此选项，则将使用 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> 指定的文件（如果未present 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 版本中新增。

创建指定的 <archive> 文件，包含 <paths> 中列出的文件和目录。请注意，<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 参数，并且用 bundle 可执行文件的目录替换 @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，则使用它。