source()¶

source() 方法可用于检索构建软件包所需的源代码，并在必要时对这些源代码应用补丁。当软件包从源代码构建时（例如使用 conan create 或 conan install --build=pkg*），将会调用此方法，但如果使用预编译的二进制文件，则不会调用。这意味着如果存在预编译的二进制文件，则不会下载源代码。

source() 方法可以实现不同的源代码检索策略

获取第三方库的源代码
- 使用 Git(self).clone() 克隆 Git 仓库
- 执行 download() + unzip() 或组合的 get()（内部执行下载 + 解压）来下载 tarball、tgz 或 zip 归档文件。
获取自身的源代码，从其仓库中获取，其坐标已在 export() 方法的 conandata.yml 文件中捕获。这是用于管理软件包源代码的策略，在这种情况下，conanfile.py 文件位于软件包本身，但出于某种原因我们不想将源代码放在配方中（例如，不分发我们的源代码，但能够分发我们的软件包二进制文件）。

source() 方法在 self.source_folder 中执行，当前工作目录将等于该文件夹（其值来自 layout() 方法）。

source() 实现可以使用方便的 get() 助手，或使用自己的机制或其他 Conan 辅助工具来完成任务，例如

import os
import shutil

from conan import ConanFile
from conan.tools.files import download, unzip, check_sha1


class PocoConan(ConanFile):
    name = "poco"
    version = "1.6.0"

    def source(self):
        zip_name = f"poco-{self.version}-release.zip"
        # Immutable source .zip
        download(self, f"https://github.com/pocoproject/poco/archive/poco-{self.version}-release.zip", zip_name)
        # Recommended practice, always check hashes of downloaded files
        check_sha1(self, zip_name, "8d87812ce591ced8ce3a022beec1df1c8b2fac87")
        unzip(self, zip_name)
        shutil.move(f"poco-poco-{self.version}-release", "poco")
        os.unlink(zip_name)

重要

请阅读 conan.tools.files.unzip() 中的说明，了解 Python 3.14 的重大更改以及新的 tar 归档提取过滤器。

可以在 source() 方法中应用补丁（并且应该这样做），如果这些补丁适用于所有可能的配置。如下所述，无法在 source() 方法中引入条件。如果补丁是文件形式的，那么这些补丁必须与配方一起导出，以便在触发从源代码构建时可以使用它们。

可以使用以下方法应用补丁：

您自己的或 git 补丁工具
Conan 内置的 patch() 工具，用于显式地逐个应用补丁
使用 Conan 工具 apply_conandata_patches() 自动应用 conandata.yml 文件中定义的、遵循某些约定的所有补丁。

源代码缓存¶

调用 source() 方法后，其结果将被缓存并重用于任何从源代码构建的、任何配置的构建。这意味着从 source() 方法检索源代码应该与配置完全无关。无法在 settings 中实现条件，通常，任何试图对 source() 方法应用条件逻辑的尝试都是错误的。

def source(self):
    if self.settings.compiler == "gcc":  # ERROR, will raise
        # download some source

尝试绕过 Conan 异常，使用其他机制，例如

def source(self):
    # Might work, but NOT recommended, try to avoid as much as possible
    if platform.system() == "Windows":
        # download something
    else:
        # download something different

在不进行交叉构建，并且不在不同操作系统中重新收集源代码的情况下，这可能看似有效，但否则可能存在问题。

为完全安全起见，如果不同配置需要不同的源代码，推荐的方法是在 build() 方法中条件性地检索代码。

强制检索源代码¶

当在用户文件夹中处理配方时，可以轻松调用 source() 方法并强制检索源代码，这将根据 layout() 定义在同一个用户文件夹中进行。

$ conan source .

通过 tools.build:download_source=True 配置，可以调用 source() 方法并强制在缓存中检索源代码，针对所有或部分依赖项，即使它们不是从源代码构建的。例如

$ conan graph info . -c tools.build:download_source=True

将计算依赖图，然后为图中的所有“主机”包调用 source() 方法（因为默认配置是“主机”配置，如果您还想要“构建”上下文 tool_requires 的源代码，您可以使用 -c:b tools.build:download_source=True）。可以通过 JSON 格式的输出来收集所有源文件夹，或者自动化收集所有源，可以使用 deployer。

同样，可以通过传递配置来检索其他 create 和 install 命令中软件包的源代码。最后，由于配置也可以按包定义，使用 -c mypkg*:tools.build:download_source=True 将仅检索匹配 mypkg* 模式的软件包的源代码。

请注意，tools.build:download_source=True 对 **可编辑** 模式下的软件包无效。在这种情况下下载源代码很容易覆盖和破坏本地开发人员对该代码所做的更改。在可编辑模式下下载源代码必须使用 conan source 命令。

注意

最佳实践

source() 方法对于所有配置都应该是相同的，它不能依赖于任何配置。
source() 方法应检索不可变的源代码。使用分支名称、HEAD 或 URL 不可变且正在被覆盖的 tarball 是不良做法，会导致软件包损坏。使用 Git 提交、冻结的 Git 发布标签或固定版本化的发布 tarball 是预期输入。
补丁应用默认应在 source() 方法中完成，除非补丁仅适用于一个配置，在这种情况下，它们可以在 build() 方法中应用。
source() 方法不应访问或操作 self.source_folder 以外的任何文件夹中的文件。所有“导出的”文件在调用它之前都会被复制到 self.source_folder。

另请参阅

有关更多信息，请参阅关于管理配方源的教程。