文件

文件操作命令。

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

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

备注

子命令 RELATIVE_PATH、TO_CMAKE_PATH 和 TO_NATIVE_PATH 已分别被子命令取代:ref:RELATIVE_PATH <cmake_path-RELATIVE_PATH>、 CONVERT ... TO_CMAKE_PATH_LIST 和 CONVERT ... TO_NATIVE_PATH_LIST of cmake_path() 命令。

概要

Reading
  file(READ <filename> <out-var> [...])
  file(STRINGS <filename> <out-var> [...])
  file(<HASH> <filename> <out-var>)
  file(TIMESTAMP <filename> <out-var> [...])
  file(GET_RUNTIME_DEPENDENCIES [...])

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 [<dir>...])
  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> [...])

阅读

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 <最大长度>

只考虑最多给定长度的字符串。

LENGTH_MINIMUM <最小长度>

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

限制计数 <max-number>

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

LIMIT_INPUT <最大输入>

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

LIMIT_OUTPUT <最大输出>

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

NEWLINE_CONSUME

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

NO_HEX_CONVERSION

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

REGEX <正则表达式>

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

ENCODING <编码类型>

在 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(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>...]]
  )

在 3.16 版本加入.

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

请注意，此子命令不适用于项目模式。它旨在在安装时使用，可以从 install(RUNTIME_DEPENDENCY_SET) 命令生成的代码，或者来自项目通过 install(CODE) 或 install(脚本）()。例如：

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>”中。

可执行文件 <executable_files>

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

库 <library_files>

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

模块 <module_files>

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

DIRECTORIES <目录>

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

BUNDLE_EXECUTABLE <bundle_executable_file>

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

以下参数指定用于包含或排除要解析的库的过滤器。有关它们如何工作的完整说明，请参见下文。

PRE_INCLUDE_REGEXES <正则表达式>

预包含正则表达式列表，用于过滤尚未解析的依赖项的名称。

PRE_EXCLUDE_REGEXES <正则表达式>

预先排除的正则表达式列表，用于过滤尚未解决的依赖项的名称。

POST_INCLUDE_REGEXES <正则表达式>

post-include 正则表达式列表，用于过滤已解析依赖项的名称。

POST_EXCLUDE_REGEXES <正则表达式>

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

POST_INCLUDE_FILES <文件>

在 3.21 版本加入.

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

POST_EXCLUDE_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. 否则，依赖关系无法解决。

在 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”。）

   请注意，任何解析的 DLL 的目录部分都保留其大小写，不会转换为小写。仅转换文件名部分。

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

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

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

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

6. 否则，依赖关系无法解决。

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

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

2. 否则，如果依赖项以“@executable_path/”开头，并且有一个“BUNDLE_EXECUTABLE”参数，并且将“@executable_path/”替换为捆绑可执行文件的目录会产生一个现有文件，则依赖项是解析到那个文件。

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

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

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

6. 否则，依赖关系无法解决。

此函数接受几个变量，这些变量确定使用哪个工具来解决依赖关系：

CMAKE_GET_RUNTIME_DEPENDENCIES_PLATFORM

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

• linux+精灵

• windows+pe

• macos+猛男

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

CMAKE_GET_RUNTIME_DEPENDENCIES_TOOL

确定用于依赖项解析的工具。它可以是几个值之一，具体取决于 CMAKE_GET_RUNTIME_DEPENDENCIES_PLATFORM 的值：

CMAKE_GET_RUNTIME_DEPENDENCIES_PLATFORM	CMAKE_GET_RUNTIME_DEPENDENCIES_TOOL
linux+精灵	objdump
windows+pe	垃圾箱
windows+pe	objdump
macos+猛男	otool

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

CMAKE_GET_RUNTIME_DEPENDENCIES_COMMAND

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

如果未指定此变量，则由“CMAKE_OBJDUMP”的值（如果已设置）确定，否则由系统自检确定。

在 3.18 版本加入: 如果设置，请使用 CMAKE_OBJDUMP。

写作

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 不会修改现有文件的内容。

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

为当前 CMake Generator 支持的每个构建配置生成一个输出文件。从输入内容中计算生成器表达式 <cmake-generator-expressions(7)> 以生成输出内容。选项是：

条件<条件>

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

内容<内容>

使用明确给出的内容作为输入。

INPUT <输入文件>

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

在 3.10 版本发生变更: 相对路径根据 CMAKE_CURRENT_SOURCE_DIR 的值进行处理。请参阅政策:policy:CMP0070。

OUTPUT <输出文件>

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

在 3.10 版本发生变更: 相对路径（在评估生成器表达式之后）根据 CMAKE_CURRENT_BINARY_DIR 的值进行处理。请参阅政策:policy:CMP0070。

目标<目标>

在 3.19 版本加入.

指定在评估需要评估目标的生成器表达式时使用哪个目标（例如:genex:$<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 <权限>...

在 3.20 版本加入.

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

NEWLINE_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 <输出文件>

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

内容<内容>

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

ESCAPE_QUOTES

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

@只有

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

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

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

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

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

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

备注

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

通配表达式的示例包括：

*.cxx      - match all files with extension cxx
*.vt?      - match all files with extension vta,...,vtz
f[3-5].txt - match files f3.txt, f4.txt, f5.txt

GLOB_RECURSE 模式会遍历匹配目录的所有子目录，匹配文件。只有在给出“FOLLOW_SYMLINKS”或策略:policy:“CMP0009”未设置为“NEW”时，才会遍历作为符号链接的子目录。

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

递归通配符的示例包括：

/dir/*.py  - match all python files in /dir and subdirectories

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

根据需要创建给定目录及其父目录。

file(REMOVE [<files>...])
file(REMOVE_RECURSE [<files>...])

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

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

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

将文件系统中的文件或目录从 <oldname> 移动到 <newname>，以原子方式替换目标。

选项是：

结果<结果>

在 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>”变量设置为“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|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) 子命令可能更容易使用。

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

在 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。

有效的关键字组合是：

权限

所有项目都已更改。

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 <目录>

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

EXPAND_TILDE

在 3.21 版本加入.

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

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 <秒数>

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

日志<变量>

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

显示进度

将进度信息打印为状态消息，直到操作完成。

状态<变量>

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

超时<秒>

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

USERPWD <用户名>:<密码>

在 3.7 版本加入.

设置用户名和密码进行操作。

HTTPHEADER <HTTP 标头>

在 3.7 版本加入.

用于操作的 HTTP 标头。子选项可以重复多次。

NETRC <级别>

在 3.11 版本加入.

指定是否使用.netrc 文件进行操作。如果未指定此选项，则将使用 CMAKE_NETRC 变量的值。有效级别是：

忽略

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

可选的

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

需要

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

NETRC_FILE <文件>

在 3.11 版本加入.

如果 NETRC 级别是 OPTIONAL 或 REQUIRED，请在您的主目录中指定一个替代 .netrc 文件。如果未指定此选项，则将使用 CMAKE_NETRC_FILE 变量的值。

TLS_VERIFY <ON|OFF>

指定是否验证 https:// URL 的服务器证书。默认是*不*验证。如果未指定此选项，则将使用 CMAKE_TLS_VERIFY 变量的值。

在 3.18 版本加入: 添加了对“文件（上传）”的支持。

TLS_CAINFO <文件>

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

在 3.18 版本加入: 添加了对“文件（上传）”的支持。

对于 https:// URL，CMake 必须使用 OpenSSL 支持来构建。默认情况下不检查 TLS/SSL 证书。将 TLS_VERIFY 设置为 ON 以检查证书。

DOWNLOAD 的附加选项是：

EXPECTED_HASH 算法=<值>

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

EXPECTED_MD5 <值>

EXPECTED_HASH MD5=<value> 的历史简写。如果没有给 <file> DOWNLOAD 指定这个是错误的。

RANGE_START <值>

在 3.24 版本加入.

文件中范围开始的偏移量（以字节为单位）。可以省略以下载指定的``RANGE_END``。

RANGE_END <值>

在 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。文件将被锁定在“保护”选项定义的范围内（默认值为“进程”）。 RELEASE 选项可用于显式解锁文件。如果未指定选项 TIMEOUT CMake 将等待锁定成功或发生致命错误。如果 TIMEOUT 设置为 0 锁定将尝试一次并立即报告结果。如果 TIMEOUT 不是 0 CMake 将尝试在 <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>]
  [VERBOSE])

在 3.18 版本加入.

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

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

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

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

在 3.26 版本加入: Zstd 算法的``<compression-level>`` 可以设置在 0-19 之间。

备注

将 FORMAT 设置为 raw 只有一个文件将使用 COMPRESSION 指定的压缩类型进行压缩。

VERBOSE 选项为存档操作启用详细输出。

要指定 tarball 条目中记录的修改时间，请使用“MTIME”选项。

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

在 3.18 版本加入.

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

可以使用 DESTINATION 选项指定存档内容将被提取到的目录。如果该目录不存在，将创建它。如果没有给出``DESTINATION``，将使用当前的二进制目录。

如果需要，您可以使用指定的 <patterns> 选择要列出或从存档中提取的文件和目录。支持通配符。如果没有给出 PATTERNS 选项，将列出或提取整个档案。

LIST_ONLY 将列出存档中的文件而不是提取它们。

在 3.24 版本加入: TOUCH 选项为提取的文件提供当前本地时间戳，而不是从存档中提取文件时间戳。

使用 VERBOSE，该命令将产生详细的输出。