文件¶

文件操作命令。

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

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

注意

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

语法¶

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> 中。如果命令无法获取时间戳，则变量将被设置为空字符串（""）。

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

写入¶

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>）来指定特定于配置的输出文件名。多个配置可能生成相同的文件，前提是生成的内容相同。否则，<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），则这已经是默认行为。在没有 INPUT 的情况下指定此选项是错误的。

FILE_PERMISSIONS <permissions>...

在版本 3.20 中添加。

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

NEWLINE_STYLE <style>

在版本 3.20 中添加。

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

必须给出恰好一个 CONTENT 或 INPUT 选项。最多可以使用一次 file(GENERATE) 调用来命名特定的 OUTPUT 文件。仅当生成的文件内容发生更改时，才会在随后的 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 上才有意义，在 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.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 中添加。

指定与您 home 目录中的 .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 环境变量的值。如果两者都未设置，则默认值为 *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 命令锁定任何子目录或文件。

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

归档¶

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 中已添加。

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

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

如果尚未解析的依赖项与任何 PRE_INCLUDE_REGEXES 匹配，则跳过步骤 2 和 3，依赖项解析继续进行步骤 4。
如果尚未解析的依赖项与任何 PRE_EXCLUDE_REGEXES 匹配，则该依赖项的依赖项解析停止。
否则，依赖项解析继续进行。
file(GET_RUNTIME_DEPENDENCIES) 根据平台的链接规则（见下文）搜索依赖项。
如果找到依赖项，并且其完整路径与任何 POST_INCLUDE_REGEXES 或 POST_INCLUDE_FILES 匹配，则完整路径将添加到已解析的依赖项中，并且 file(GET_RUNTIME_DEPENDENCIES) 会递归地解析该库自己的依赖项。否则，解析继续进行步骤 6。
如果找到依赖项，但其完整路径与任何 POST_EXCLUDE_REGEXES 或 POST_EXCLUDE_FILES 匹配，则它不会被添加到已解析的依赖项中，并且该依赖项的依赖项解析停止。
如果找到依赖项，并且其完整路径与 POST_INCLUDE_REGEXES、POST_INCLUDE_FILES、POST_EXCLUDE_REGEXES 或 POST_EXCLUDE_FILES 均不匹配，则完整路径将添加到已解析的依赖项中，并且 file(GET_RUNTIME_DEPENDENCIES) 会递归地解析该库自己的依赖项。

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

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

如果依赖文件没有任何 RUNPATH 条目，并且库存在依赖文件的一个 RPATH 条目中，或者其父目录中，则按照该顺序解析依赖项。
否则，如果依赖文件有任何 RUNPATH 条目，并且库存在这些条目中的一个中，则解析依赖项。
否则，如果库存在 ldconfig 列出的目录之一中，则解析依赖项。
否则，如果库存在 DIRECTORIES 条目中的一个中，则解析依赖项。在这种情况下，会发出警告，因为在 DIRECTORIES 中的某一个中找到文件意味着依赖文件不完整（它没有列出它从中提取依赖项的所有目录）。
否则，依赖项未解析。

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

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

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 文件名报告，但目录部分保留其大小写。
（**尚未实现**）如果依赖文件是 Windows Store 应用，并且依赖项在应用程序的包清单中列出，则解析依赖项。
否则，如果库存在与依赖文件相同的目录中，则解析依赖项。
否则，如果库存在操作系统的 system32 目录或 Windows 目录中，则按照该顺序解析依赖项。
否则，如果库存在 DIRECTORIES 指定的目录之一中，则按照列出的顺序解析依赖项。在这种情况下，不会发出警告，因为搜索其他目录是 Windows 库解析的正常部分。
否则，依赖项未解析。

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

如果依赖项以 @executable_path/ 开头，并且 EXECUTABLES 参数正在被解析，并且用可执行文件的目录替换 @executable_path/ 会生成一个现有文件，则解析依赖项。
否则，如果依赖项以 @executable_path/ 开头，并且有一个 BUNDLE_EXECUTABLE 参数，并且用捆绑包可执行文件的目录替换 @executable_path/ 会生成一个现有文件，则解析依赖项。
否则，如果依赖项以 @loader_path/ 开头，并且用依赖文件的目录替换 @loader_path/ 会生成一个现有文件，则解析依赖项。
否则，如果依赖项以 @rpath/ 开头，并且用依赖文件的一个 RPATH 条目替换 @rpath/ 会生成一个现有文件，则解析依赖项。请注意，以 @executable_path/ 或 @loader_path/ 开头的 RPATH 条目也会将这些项替换为相应的路径。
否则，如果依赖项是存在的绝对文件，则解析依赖项。
否则，依赖项未解析。

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

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，则使用它。

文件¶

语法¶

读取¶

写入¶

文件系统¶

路径转换¶

传输¶

锁定¶

归档¶

处理运行时二进制文件¶

目录

前一主题

下一主题

此页面