cmake：file

妖狐艹你老母 2022-10-11 14:55 4阅读 0赞

文件操作命令。

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

对于其他仅处理语法方面的路径操作，请查看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(RENAME <oldname> <newname> [...])
      file(COPY_FILE <oldname> <newname> [...])
      file({
        REMOVE | REMOVE_RECURSE } [<files>...])
      file(MAKE_DIRECTORY [<dir>...])
      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 >的文件中读取内容并将其存储在 中。可选地从给定的< offset >开始，最多读取< max-in >字节。HEX选项使数据转换为十六进制表示（对二进制数据有用）。如果指定了HEX选项，则输出中的字母（a到f）为小写。

file(STRINGS <filename> <variable> [<options>...])

从< filename >解析ASCII字符串列表并将其存储在< variable >中。忽略文件中的二进制数据。忽略回车符（\\r，CR）。options包括：

*  LENGTH\_MAXIMUM < max-len >：只考虑不超过给定长度的字符串。
 *  LENGTH\_MINIMUM < min-len >：只考虑至少具有给定长度的字符串。
 *  LIMIT\_COUNT < max-num >：限制要提取的不同字符串的数量。
 *  LIMIT\_COUNT < max-in >：限制从文件中读取的输入字节数。
 *  LIMIT\_OUTPUT < max-out >：限制< variable >中存储的总字节数。
 *  NEWLINE\_CONSUME：将换行符(\\n, LF)作为字符串内容的一部分，而不是终止于它们。
 *  NO\_HEX\_CONVERSION：除非给出此选项，否则读取时Intel Hex和Motorola S-record文件会自动转换为二进制文件。
 *  REGEX < regex>：只考虑匹配给定正则表达式的字符串，如string(REGEX)所述。
 *  ENCODING < encoding-type>：
    
     *  版本3.1中的新功能。
     *  考虑给定编码的字符串。目前支持的编码有：UTF-8、UTF-16LE、UTF-16BE、UTF-32LE、UTF-32BE。如果没有提供编码选项，并且文件具有字节顺序标记，则默认情况下，编码选项将遵循字节顺序标记。
     *  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新版功能。
 *  递归地获得给定文件所依赖的库列表。
 *  请注意，此子命令不打算在项目模式下使用。相反，在安装(CODE)或安装(SCRIPT)块中使用它。例如:

install(CODE [[
      file(GET_RUNTIME_DEPENDENCIES
        # ...
        )
      ]])

# 写 #

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

为当前CMake生成器支持的每个构建配置生成一个输出文件。从输入内容计算生成器表达式以生成输出内容。 option选项如下：

*  CONDITION < condition>
    
     *  仅当条件为真时，才为特定配置生成输出文件。
     *  对生成器表达式求值后，条件必须为0或1。
 *  CONTENT < content>
    
     *  使用显式给出的内容作为输入。
 *  INPUT < input-file>
    
     *  使用给定文件中的内容作为输入。

…

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()的行为，输出和内容都不支持生成器表达式。

# 文件系统 #

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

在版本3.6中更改：结果将按字典顺序排列。

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

3.3新版功能:默认情况下GLOB会列出目录-如果LIST\_DIRECTORIES设置为false，则在result中省略目录。

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

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

globbing表达式的示例包括

*.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(RENAME <oldname> <newname>
         [RESULT <result>]
         [NO_REPLACE])

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

选项包括：

*  RESULT < result>
    
     *  如果成功，则将< result >变量设置为0，否则将显示错误消息。如果未指定RESULT且操作失败，则会触发一个错误。
 *  NO\_REPLACE
    
     *  如果< newname >路径已经存在，请不要替换。如果使用RESULT < RESULT >，则RESULT变量将被设置为NO\_REPLACE。否则，将触发一个错误。

file(COPY_FILE <oldname> <newname>
         [RESULT <result>]
         [ONLY_IF_DIFFERENT])

将文件从< oldname>复制到< newname>。不支持目录。符号链接将被忽略，< oldfile>的内容将作为新文件读写到< newname>。

选项包括：

*  RESULT < result>
    
     *  如果成功，则将< result >变量设置为0，否则将显示错误消息。如果未指定RESULT且操作失败，则会触发一个错误。
 *  ONLY\_IF\_DIFFERENT
    
     *  如果< newname>路径已经存在，请不要将其替换为与< oldname>相同的路径。否则，将触发一个错误。

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

删除给定的文件。REMOVE\_RECURSE模式将删除给定的文件和目录，也是非空目录。如果给定的文件不存在，则不会触发错误。相对输入路径相对于当前源目录进行计算。

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

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

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(SIZE <filename> <variable>)

3.14新版功能。

确定的文件大小，并将结果放在变量中。要求是一个指向文件的有效路径，并且是可读的。

file(READ_SYMLINK <linkname> <variable>)

版本3.14中的新功能。

这个子命令查询symlink< linkname>并将它指向的路径存储在result< 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新版功能。

创建一个链接< linkname >，指向< original >。默认情况下，它将是一个硬链接，但是提供SYMBOLIC选项将导致一个符号链接。硬链接要求原始文件存在，并且是一个文件，而不是一个目录。如果< linkname >已经存在，它将被覆盖。

< result >变量(如果指定)接收操作的状态。成功时将其设置为0，否则将出现错误消息。如果未指定RESULT且操作失败，则会触发致命错误。

指定COPY\_ON\_ERROR将在创建链接失败时复制文件作为一种回退。它对于处理诸如< original >和< linkname >位于不同驱动器或挂载点的情况很有用，这将使它们无法支持硬链接。

file(CHMOD <files>... <directories>...
        [PERMISSIONS <permissions>...]
        [FILE_PERMISSIONS <permissions>...]
        [DIRECTORY_PERMISSIONS <permissions>...])