conan.tools.files 基本操作

conan.tools.files.copy()

copy(conanfile, pattern, src, dst, keep_path=True, excludes=None, ignore_case=True, overwrite_equal=False)

将源文件夹中与模式（fnmatch）匹配的文件复制到目标文件夹。

参数：

  • conanfile – 当前配方对象。始终使用 self。

  • pattern – （必填）要复制的文件的 fnmatch 文件模式。它不能以 .. 相对路径开头，否则将引发异常。

  • src – （必填）将在其中搜索这些文件的源文件夹。此文件夹将从 dst 参数中剥离。例如，lib/Debug/x86。

  • dst – （必填）目标本地文件夹。它必须与 src 值不同，否则将引发异常。

  • keep_path – （可选，默认为 True）表示是否希望在将文件从 src 文件夹复制到 dst 文件夹时保留相对路径。

  • excludes – （可选，默认为 None）要从复制中排除的 fnmatch 模式元组/列表，甚至单个模式。

  • ignore_case – （可选，默认为 True）如果启用，则执行不区分大小写的模式匹配。当 True 时，将执行不区分大小写的模式匹配

  • overwrite_equal – （可选，默认为 False）。如果要复制的文件已存在于目标文件夹中，则仅当它看起来不同（大小不同，修改时间不同）时才真正复制它

返回值：

已复制文件的列表

用法

def package(self):
    copy(self, "*.h", self.source_folder, os.path.join(self.package_folder, "include"))
    copy(self, "*.lib", self.build_folder, os.path.join(self.package_folder, "lib"))

注意

指向文件的符号链接或指向文件夹的符号链接将像任何其他文件一样被处理，因此只有在指定的模式与文件匹配时才会复制它们。

在目标文件夹中，将创建指向完全相同的文件或文件夹（绝对或相对）的符号链接，用户有责任操作符号链接，例如，在复制符号链接之前将其转换为相对路径，以便它指向目标文件夹。

查看 此处 管理符号链接的工具参考。

conan.tools.files.load()

load(conanfile, path, encoding='utf-8')

用于在一行中加载文件的实用程序函数。它将管理文件的打开和关闭，并加载二进制编码。返回文件的内容。

参数：

  • conanfile – 当前配方对象。始终使用 self。

  • path – 要读取的文件的路径

  • encoding – （可选，默认为 utf-8）：指定输入文件文本编码。

返回值：

文件的内容

用法

from conan.tools.files import load

content = load(self, "myfile.txt")

conan.tools.files.save()

save(conanfile, path, content, append=False, encoding='utf-8')

用于在一行中保存文件的实用程序函数。它将管理文件的打开和关闭，并在必要时创建目录。

参数：

  • conanfile – 当前配方对象。始终使用 self。

  • path – 要创建的文件的路径。

  • content – 要写入文件的内容（str 或 bytes）。

  • append – （可选，默认为 False）：如果 True，则内容将追加到现有内容。

  • encoding – （可选，默认为 utf-8）：指定输出文件文本编码。

用法

from conan.tools.files import save

save(self, "path/to/otherfile.txt", "contents of the file")

conan.tools.files.rename()

rename(conanfile, src, dst)

用于将文件或文件夹 src 重命名为 dst 并重试的实用程序函数。 os.rename() 在 Windows 上经常引发“拒绝访问”异常。此函数使用 robocopy 重命名文件或文件夹，以避免在 Windows 上出现此异常。

参数：

  • conanfile – 当前配方对象。始终使用 self。

  • src – 要重命名的路径。

  • dst – 要重命名的路径。

用法

from conan.tools.files import rename

def source(self):
    rename(self, "lib-sources-abe2h9fe", "sources")  # renaming a folder

conan.tools.files.replace_in_file()

replace_in_file(conanfile, file_path, search, replace, strict=True, encoding='utf-8')

用字符串 replace 替换文件 file_path 内容中的字符串 search。

参数：

  • conanfile – 当前配方对象。始终使用 self。

  • file_path – 执行替换的文件路径。

  • search – 要替换的字符串。

  • replace – 用于替换搜索字符串的字符串。

  • strict – （可选，默认为 True）如果 True，则如果未找到搜索字符串，则会引发错误，因此实际上不会进行任何替换。

  • encoding – （可选，默认为 utf-8）：指定输入和输出文件的文本编码。

用法

from conan.tools.files import replace_in_file

replace_in_file(self, os.path.join(self.source_folder, "folder", "file.txt"), "foo", "bar")

conan.tools.files.rm()

此函数从文件系统中删除文件。它可用于删除单个文件或基于 fnmatch 的模式。建议使用它而不是 os.remove，因为它跨平台并且可以避免权限问题。

从 build_folder 中递归删除所有以 .tmp 结尾的文件
from conan.tools.files import rm

rm(self, "*.tmp", self.build_folder, recursive=True)
删除 bin_folder 中的所有文件，除了任何以 .dll 结尾的文件
from conan.tools.files import rm

rm(self, "*", self.bin_folder, recursive=False, excludes="*.dll")
rm(conanfile, pattern, folder, recursive=False, excludes=None)

用于删除 folder 中与 pattern 匹配的文件的实用程序函数。

参数：

  • conanfile – 当前配方对象。始终使用 self。

  • pattern – 要删除的文件必须匹配的模式（fnmatch）。

  • folder – 搜索/删除文件的文件夹。

  • recursive – 如果指定了 recursive，它将在子文件夹中搜索。

  • excludes – （可选，默认为 None）要从删除模式中排除的 fnmatch 模式元组/列表，甚至单个模式。

conan.tools.files.mkdir()

mkdir(conanfile, path)

用于创建目录的实用程序函数。会检查指定目录是否存在，因此如果目录已存在，则 mkdir() 不会执行任何操作。

参数：

  • conanfile – 当前配方对象。始终使用 self。

  • path – 要创建的文件夹的路径。

用法

from conan.tools.files import mkdir

mkdir(self, "mydir") # Creates mydir if it does not already exist
mkdir(self, "mydir") # Does nothing

conan.tools.files.rmdir()

rmdir(conanfile, path)

用法

from conan.tools.files import rmdir

rmdir(self, "mydir") # Remove mydir if it exist
rmdir(self, "mydir") # Does nothing

conan.tools.files.chdir()

chdir(conanfile, newdir)

这是一个上下文管理器，允许在您的conanfile中临时更改当前目录。

参数：

  • conanfile – 当前配方对象。始终使用 self。

  • newdir – 要更改为的目录路径名称。

用法

from conan.tools.files import chdir

def build(self):
    with chdir(self, "./subdir"):
        do_something()

conan.tools.files.unzip()

此函数将不同的压缩格式（.tar、.tar.gz、.tgz、.tar.bz2、.tbz2、.tar.xz、.txz和.zip）解压缩到给定的目标文件夹中。

它也接受扩展名为.gz（与上述任何一个都不匹配）的gzip文件，并将它们解压缩到具有相同名称但没有扩展名的文件中，或解压缩到由destination参数定义的文件名中。

from conan.tools.files import unzip

unzip(self, "myfile.zip")
# or to extract in "myfolder" sub-folder
unzip(self, "myfile.zip", "myfolder")

您可以使用keep_permissions=True参数保留文件的权限。

from conan.tools.files import unzip

unzip(self, "myfile.zip", "myfolder", keep_permissions=True)

如果您想过滤要从存档中解压缩的特定文件和路径，请使用pattern参数。

from conan.tools.files import unzip

# Extract only files inside relative folder "small"
unzip(self, "bigfile.zip", pattern="small/*")
# Extract only txt files
unzip(self, "bigfile.zip", pattern="*.txt")

重要

在Conan 2.8中，unzip()提供了一个新的extract_filter=None参数，并且添加了一个新的tools.files.unzip:filter配置，以准备应对未来Python 3.14的重大更改，在这些更改中，用于提取tar存档的data过滤器将成为默认过滤器。建议尽快开始使用data过滤器（可以在global.conf中定义conf，或者可以在配方中作为参数显式添加unzip()和get()辅助函数），因为这是当前从互联网下载源时的安全建议。

unzip(conanfile, filename, destination='.', keep_permissions=False, pattern=None, strip_root=False, extract_filter=None)

解压缩不同的压缩格式

参数：

  • conanfile – 当前配方对象。始终使用 self。

  • filename – 压缩文件的路径。

  • destination – （可选，默认为.）目标文件夹（或.gz文件的目标文件）

  • keep_permissions – （可选，默认为False）保留zip权限。警告：如果zip不是在NIX系统中创建的，则可能很危险，位可能会产生未定义的权限模式。仅当您确定zip创建正确时才使用此选项。

  • pattern – （可选，默认为None）仅提取与模式匹配的路径。这应该是一个Unix shell风格的通配符，有关更多详细信息，请参阅fnmatch文档。

  • strip_root – （可选，默认为False）如果为True，并且所有解压缩的内容都在单个文件夹中，它将展平文件夹并将所有内容移动到父文件夹。

  • extract_filter – （可选，默认为None）。在提取tar文件时，使用Python在https://docs.pythonlang.cn/3/library/tarfile.html中定义的tar提取过滤器

conan.tools.files.update_conandata()

此函数读取conan缓存中导出文件夹内的conandata.yml（如果存在）。如果conandata.yml不存在，它将创建它。然后，它使用提供的data更新conandata字典，该字典是递归更新的，优先考虑data的值，但保留其他现有的值。最后，conandata.yml保存在相同的位置。

此辅助函数只能在export()方法中使用，否则可能会引发异常。一个应用是在conandata.yml中捕获scm坐标（如Git远程URL和提交），以便以后在source()方法中恢复它，并拥有可以在不实际存储源代码的情况下从源代码构建的可重复配方。

update_conandata(conanfile, data)

用于修改conandata.yml的工具，在导出后可以使用。例如，它可以用于

  • 添加其他数据，例如scm的“提交”和“URL”。

  • 修改内容，清除属于其他版本（与导出版本不同）的数据，以避免在更改的数据不属于当前版本时更改配方修订版本。

参数：

  • conanfile – 当前配方对象。始终使用 self。

  • data – （必需）要更新的值的字典（可以嵌套）。

conan.tools.files.trim_conandata()

trim_conandata(conanfile, raise_if_missing=True)

用于修改conandata.yml的工具，在导出后可以使用，以将其限制为仅当前版本。

警告

conan.tools.files.trim_conandata()函数处于**预览**状态。有关更多信息，请参阅Conan稳定性部分。

此函数修改conan缓存中导出文件夹内的conandata.yml（如果存在），并仅保留与当前构建版本相关的信息。

此辅助函数只能在export()方法或post_export()钩子中使用，否则将来可能会引发异常。一个应用是确保与某些版本相关的conandata.yml文件中的更改不会影响其余生成的配方修订版本。

用法

from conan import ConanFile
from conan.tools.files import trim_conandata

class Pkg(ConanFile):
    name = "pkg"

    def export(self):
        # any change to other versions in the conandata.yml
        # won't affect the revision of the version that is built
        trim_conandata(self)

conan.tools.files.collect_libs()

collect_libs(conanfile, folder=None)

从位于conanfile.cpp_info.libdirs（默认）或相对于包文件夹的folder目录中的库（扩展名为.so、.lib、.a和.dylib的文件）中返回一个排序的库名称列表。对于收集不相互依赖的库或具有复杂名称（如libmylib-x86-debug-en.lib）的库很有用。

对于以lib开头的UNIX库，例如libmath.a，此工具将收集库名称math。

参数：

  • conanfile – 当前配方对象。始终使用 self。

  • folder – （可选，默认为None）：字符串，指示库文件所在的conanfile.package_folder内部的子文件夹名称。

返回值：

包含库名称的列表

警告

此工具直接在包文件夹内搜索库并返回它们，且没有特定的顺序。如果库之间存在依赖关系，则package_info()方法应对其进行排序以实现正确的链接顺序。

用法

from conan.tools.files import collect_libs

def package_info(self):
    self.cpp_info.libdirs = ["lib", "other_libdir"]  # Default value is 'lib'
    self.cpp_info.libs = collect_libs(self)

对于以lib开头的UNIX库，例如libmath.a，此工具将收集库名称math。关于符号链接，此工具将仅保留已解析的真实文件和所有指向此真实文件的符号链接中最“通用”的文件。例如，在下面的文件中，此工具将选择libmath.dylib文件，因此仅将math附加到返回的列表中

-rwxr-xr-x libmath.1.0.0.dylib lrwxr-xr-x libmath.1.dylib -> libmath.1.0.0.dylib
lrwxr-xr-x libmath.dylib -> libmath.1.dylib