conan.tools.files 基本操作¶

conan.tools.files.copy()¶

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

将 src 文件夹中与模式 (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"))

注意

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

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

在此处检查管理符号链接的工具的参考资料 here。

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 – 要写入文件的内容（字符串或字节）。
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)：指定输入和输出文件文本编码。

返回值:

如果找到该模式，则为 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 上，仅限于更改写权限。

参数¶

conanfile对象: 当前的配方对象。始终使用 self。
path字符串: 将更改其权限的文件或目录的路径。
readbool, 可选: 如果为 True，则将为所有者用户提供文件或目录的读取权限。如果为 False，则将删除读取权限。如果为 None，则读取权限将保持不变。默认为 None。
writebool, 可选: 如果 True，则文件或目录将被授予所有者用户的写入权限。如果 False，则写入权限将被移除。如果 None，则文件或目录将不会被更改。默认为 None。
executebool, 可选: 如果 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 中定义 conf，或者可以在 recipe 中显式地添加为参数 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 中定义的 tar 提取过滤器 https://docs.pythonlang.cn/3/library/tarfile.html

conan.tools.files.update_conandata()¶

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

此助手只能在 export() 方法中使用，否则会引发错误。一种应用是在 conandata.yml 中捕获 scm 坐标（如 Git 远程 url 和提交），以便稍后可以在 source() 方法中恢复它，并拥有可重现的 recipes，这些 recipes 可以从源构建，而无需实际将源存储在 recipe 中。

update_conandata(conanfile, data)¶

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

添加其他数据，如 scm 的 “commit” 和 “url”。

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

参数:

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() hook 中使用，否则将来可能会引发错误。一种应用是确保与某些版本相关的 conandata.yml 文件中的更改不会影响其余生成的 recipe 修订。

用法

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