conan.tools.files 基本操作¶

conan.tools.files.copy()¶

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

将 src 文件夹中与 pattern (fnmatch) 匹配的文件复制到 dst 文件夹。

参数:

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')¶

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

参数:

conanfile – 当前的配方对象。始终使用 self。
file_path – 要执行替换操作的文件路径。
search – 您要替换的字符串。
replace – 替换搜索到的字符串的字符串。
strict – (可选，默认为 True) 如果 True，如果未找到搜索的字符串，则会引发错误，因此实际上没有任何替换。
encoding – (可选，默认为 utf-8)：指定输入和输出文件文本编码。

返回:

如果找到模式，则为 True；否则，如果 strict 为 False，则为 False。

用法

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.chmod()¶

chmod(conanfile, path: str, read: bool | None = None, write: bool | None = None, execute: bool | None = None, recursive: bool = False)¶

跨平台更改文件或目录权限。

2.15 版本新增。

此函数是 chmod Unix 命令的简单包装器，但它受跨平台支持。建议使用它而不是 os.stat + os.chmod，因为它只更改目录或文件所有者的权限，并避免了 umask 问题。在 Windows 上，它仅限于更改写入权限。

参数¶

conanfileobject: 当前配方对象。始终使用 self。
pathstr: 要更改权限的文件或目录的路径。
readbool, optional: 如果 True，文件或目录将获得所有者用户的读取权限。如果 False，读取权限将被移除。如果 None，读取权限将保持不变。默认为 None。
writebool, optional: 如果 True，文件或目录将获得所有者用户的写入权限。如果 False，写入权限将被移除。如果 None，文件或目录将不被更改。默认为 None。
executebool, optional: 如果 True，文件或目录将获得所有者用户的执行权限。如果 False，执行权限将被移除。如果 None，文件或目录将不被更改。默认为 None。
recursivebool: 如果 True，权限将递归应用于指定目录内的所有文件和目录。如果 False，则仅更改指定的文件或目录。默认为 False。

返回¶

None

示例¶

为打包的 bash 脚本添加执行权限¶

from conan.tools.files import chmod
chmod(self, os.path.join(self.package_folder, "bin", "script.sh"), execute=True)

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）解压到给定的目标文件夹。

它还接受 gzipped 文件，扩展名为 .gz（与上述任何文件都不匹配），它将它们解压到与原文件同名但没有扩展名的文件中，或者解压到由 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 中定义，或者可以作为参数显式添加到配方 unzip() 和 get() 助手中），因为这是从互联网下载源时的当前安全建议。

unzip(conanfile, filename, destination='.', keep_permissions=False, pattern=None, strip_root=False, extract_filter=None, excludes=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 提取过滤器
excludes – (可选，默认为 None)。提取文件时，排除与任何模式匹配的路径。这应该是一个 Unix shell 风格的通配符，请参阅 fnmatch 文档了解更多详细信息。

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 的“commit”和“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