generate()

此方法将在依赖图计算和安装后运行。这意味着它将在 conan install 命令之后运行,或者当包在缓存中构建时,它将在调用 build() 方法之前运行。

generate() 的目的是准备构建,生成必要的文件。这些文件通常是:

  • 包含定位依赖信息的文件,如 xxxx-config.cmake CMake 配置脚本,或 xxxx.props Visual Studio 属性文件。

  • 环境激活脚本,如 conanbuild.batconanbuild.sh,定义构建所需的所有必要环境变量。

  • 工具链文件,如 conan_toolchain.cmake,包含当前 Conan 设置和选项与构建系统特定语法之间的映射。对于使用现代版本的 CMake 用户,还包括 CMakePresets.json

  • 通用构建信息,如 conanbuild.conf 文件,可能包含一些工具链(如 autotools)的信息,用于 build() 方法。

  • 特定构建系统文件,如 conanvcvars.bat,包含使用 Microsoft 编译器编译时,某些构建系统(如 Ninja)所需的 Visual Studio vcvars.bat 调用。

这个想法是 generate() 方法实现所有必要的逻辑,使得用户在 conan install 后手动构建变得非常简单,并且 build() 方法的逻辑也更简单。用户在其本地流程中产生的构建应该与在缓存中使用 conan create 完成的构建完全相同,无需额外努力。

文件生成发生在当前布局定义的 generators_folder 中。

在许多情况下,generate() 方法可能不是必需的,声明 generators 属性就足够了。

from conan import ConanFile

class Pkg(ConanFile):
    generators = "CMakeDeps", "CMakeToolchain"

但是 generate() 方法可以显式地实例化这些生成器,有条件地使用它们(例如在 Windows 上使用一个构建系统,在其他平台上使用另一个构建系统集成),自定义它们,或者提供完整的自定义生成。

from conan import ConanFile
from conan.tools.cmake import CMakeToolchain

class Pkg(ConanFile):

    def generate(self):
        tc = CMakeToolchain(self)
        # customize toolchain "tc"
        tc.generate()
        # Or provide your own custom logic

generate() 方法的当前工作目录将是当前布局中定义的 self.generators_folder

对于自定义集成,将代码放入公共的 python_require 是避免在多个配方中重复的好方法。

from conan import ConanFile
from conan.tools.cmake import CMakeToolchain

class Pkg(ConanFile):

    python_requires = "mygenerator/1.0"

    def generate(self):
        mygen = self.python_requires["mygenerator"].module.MyGenerator(self)
        # customize mygen behavior, like mygen.something= True
        mygen.generate()

如果需要从依赖项中收集或复制某些文件,也可以在 generate() 方法中进行,通过访问 self.dependencies。列出依赖项“mydep”的不同包含目录和库目录可以这样做:

from conan import ConanFile

class Pkg(ConanFile):

    def generate(self):
        info = self.dependencies["mydep"].cpp_info
        self.output.info("**includedirs:{}**".format(info.includedirs))
        self.output.info("**libdirs:{}**".format(info.libdirs))
        self.output.info("**libs:{}**".format(info.libs))

将 Windows 和 OSX 上的共享库复制到当前构建文件夹可以这样做:

from conan import ConanFile

class Pkg(ConanFile):

    def generate(self):
        # NOTE: In most cases it is not necessary to copy the shared libraries
        # of dependencies to use them. Conan environment generators that create
        # environment scripts allow to use the shared dependencies without copying
        # them to the current location
        for dep in self.dependencies.values():
            # This code assumes dependencies will only have 1 libdir/bindir, if for some
            # reason they have more than one, it will fail. Use ``dep.cpp_info.libdirs``
            # and ``dep.cpp_info.bindirs`` lists for those cases.
            copy(self, "*.dylib", dep.cpp_info.libdir, self.build_folder)
            # In Windows, dlls are in the "bindir", not "libdir"
            copy(self, "*.dll", dep.cpp_info.bindir, self.build_folder)

注意

最佳实践

  • 在大多数情况下,在 generate() 中将共享库复制到当前项目不是必需的,也不应作为通用方法。相反,默认启用的 Conan 环境生成器会自动生成环境脚本,如 conanbuild.bat|.shconanrun.bat|.sh,其中包含必要的环境变量(PATHLD_LIBRARY_PATH 等),以便在运行时正确地定位和使用依赖项的共享库。

  • 可以访问依赖项的 self.dependencies["mydep"].package_folder,但当依赖项“mydep”处于“可编辑”模式时,它将是 None。如果您计划使用可编辑包,请务必始终引用 cpp_info.xxxdirs

self.dependencies

Conan 配方通过 self.dependencies 属性提供对其依赖项的访问。此属性通常由生成器(如 CMakeDepsMSBuildDeps)使用,以生成构建所需的文件。

本节介绍了 self.dependencies 属性,因为它可能由用户直接在配方中使用,或间接用于创建自定义构建集成和生成器。

依赖项接口

可以使用以下语法访问当前配方的每个独立依赖项:

class Pkg(ConanFile):
    requires = "openssl/0.1"

    def generate(self):
        openssl = self.dependencies["openssl"]
        # access to members
        openssl.ref.version
        openssl.ref.revision # recipe revision
        openssl.options
        openssl.settings

        if "zlib" in self.dependencies:
            # do something

一些重要事项:

  • 所有信息都是只读的。任何修改依赖项信息的尝试都是错误的,并且可能随时引发异常,即使目前没有引发。

  • 也无法通过此机制调用任何方法或尝试重用依赖项中的代码。

  • 此信息在某些配方方法中不存在,仅在完整依赖图计算后评估的方法中存在。它不会存在于 configure()config_optionsexport()export_source()set_name()set_version()requirements()build_requirements()system_requirements()source()init()layout() 中。任何在这些方法中使用它的尝试都可能随时引发错误。

  • 目前,此信息应仅在 generate()validate() 方法中使用。对于任何其他用途,请提交 GitHub 问题。

并非所有依赖项 conanfile 的字段都已公开,当前字段有:

  • package_folder:依赖项包二进制文件的文件夹位置

  • recipe_folder:包含依赖项的 conanfile.py(和其他导出文件)的文件夹

  • recipe_metadata_folder:包含依赖项可选配方元数据文件的文件夹

  • package_metadata_folder:包含依赖项可选包元数据文件的文件夹

  • immutable_package_folder:当 finalize() 方法存在时,包含不可变工件的文件夹

  • ref:一个包含 nameversionuserchannelrevision(配方修订版)的对象

  • pref:一个包含 refpackage_idrevision(包修订版)的对象

  • buildenv_infoEnvironment 对象,包含构建所需的环境信息

  • runenv_infoEnvironment 对象,包含运行应用程序所需的环境信息

  • cpp_info:依赖项的 includedirs、libdirs 等。

  • settings:此依赖项的实际设置值

  • settings_build:此依赖项的实际构建设置值

  • options:此依赖项的实际选项值

  • context:此依赖项的上下文(build、host)

  • conf_info:此依赖项的配置信息,旨在应用于消费者。

  • dependencies:此依赖项的传递依赖项

  • is_build_context:如果 context == "build",则返回 True

  • conan_data:来自其 conandata.yml 文件的依赖项的 conan_data 属性

  • license:依赖项的 license 属性

  • description:依赖项的 description 属性

  • homepage:依赖项的 homepage 属性

  • url:依赖项的 url 属性

  • package_type:依赖项的 package_type

  • languages:依赖项的 languages

  • extension_properties:依赖项的 extension_properties。应视为只读。

迭代依赖项

可以以类似字典的方式迭代配方中的所有依赖项。请注意,self.dependencies 包含所有当前依赖项,包括直接和传递依赖项。当前依赖项的上游依赖项中,对其有影响的每个依赖项都将在 self.dependencies 中有一个条目。

迭代依赖项可以这样做:

requires = "zlib/1.3.1", "poco/1.9.4"

def generate(self):
    for require, dependency in self.dependencies.items():
        self.output.info("Dependency is direct={}: {}".format(require.direct, dependency.ref))

将输出:

conanfile.py (hello/0.1): Dependency is direct=True: zlib/1.3.1
conanfile.py (hello/0.1): Dependency is direct=True: poco/1.9.4
conanfile.py (hello/0.1): Dependency is direct=False: pcre/8.44
conanfile.py (hello/0.1): Dependency is direct=False: expat/2.4.1
conanfile.py (hello/0.1): Dependency is direct=False: sqlite3/3.35.5
conanfile.py (hello/0.1): Dependency is direct=False: openssl/1.1.1k
conanfile.py (hello/0.1): Dependency is direct=False: bzip2/1.0.8

其中 require 字典键是一个“要求”,可以包含当前配方与依赖项之间关系的说明符。目前它们可以是:

  • require.direct:布尔值,如果它是直接依赖项则为 True,如果是传递依赖项则为 False

  • require.build:布尔值,如果它在构建上下文中是 build_require(例如 cmake),则为 True

  • require.test:布尔值,如果它在主机上下文中是 build_require(使用 self.test_requires() 定义),例如 gtest,则为 True

dependency 字典值是上面描述的只读对象,用于访问依赖项属性。

self.dependencies 包含一些辅助函数,可根据某些标准进行过滤:

  • self.dependencies.host:将过滤掉 build=True 的要求,留下像 zlibpoco 这样的常规依赖项。

  • self.dependencies.direct_host:将过滤掉 build=Truedirect=False 的要求。

  • self.dependencies.build:将过滤掉 build=False 的要求,只留下构建上下文中的 tool_requires,例如 cmake

  • self.dependencies.direct_build:将过滤掉 build=Falsedirect=False 的要求。

  • self.dependencies.test:将过滤掉 build=Truetest=False 的要求,只留下主机上下文中的测试要求,例如 gtest

它们可以以相同的方式使用:

requires = "zlib/1.3.1", "poco/1.9.4"

def generate(self):
    cmake = self.dependencies.direct_build["cmake"]
    for require, dependency in self.dependencies.build.items():
        # do something, only build deps here

依赖项 cpp_info 接口

cpp_info 接口被构建系统大量使用来访问数据。此对象定义了全局和每个组件的属性,以访问包含目录等信息:

def generate(self):
    cpp_info = self.dependencies["mydep"].cpp_info
    cpp_info.includedirs
    cpp_info.libdirs

    cpp_info.components["mycomp"].includedirs
    cpp_info.components["mycomp"].libdirs

cppinfo 对象中声明的所有路径(如 cpp_info.includedirs)都是绝对路径,无论依赖项是在缓存中还是可编辑包,它们都能正常工作。

另请参阅