属性¶

包引用 ¶

配方属性，可以定义主要的 pkg/version@user/channel 包引用。

名称 ¶

包的名称。有效的名称是全小写且具有

最少 2 个字符，最多 101 个字符（但建议使用更短的名称）。
匹配以下正则表达式 ^[a-z0-9_][a-z0-9_+.-]{1,100}$：因此，它以字母数字或 _ 开头，
然后是 1 到 100 个字符，可以是字母数字、_、+、. 或 -。

仅当使用 --name=<pkgname> 在命令行中未定义名称时，名称才对于将配方 export 到本地缓存（export、export-pkg: 和 create 命令）时才是必需的。

版本 ¶

包的版本。有效版本遵循与 name 属性相同的规则。如果版本遵循 X.Y.Z-pre1+build2 形式的语义版本控制，则该值可能用于通过版本范围而不是精确版本来请求此包。

版本仅对于在命令行中未定义版本时，将配方 export 到本地缓存（export、export-pkg 和 create 命令）才是严格必需的，除非通过 --version=<pkgversion> 定义。

版本可以在命令行中动态定义，也可以通过配方中的 set_version() 方法以编程方式定义。

有效的 user 字段字符串遵循与 name 属性相同的规则。这是一个可选属性。它可以用于识别您自己的包，例如 pkg/version@user/channel，其中 user 可以是您的团队、组织或公司的名称。ConanCenter 配方没有 user/channel，因此它们仅以 pkg/version 的形式出现。您也可以在不带用户和通道的情况下命名您的包，或者只使用用户名称，如 pkg/version@user。

可以在命令行中使用 --user=<myuser> 指定用户。

通道 ¶

有效的 channel 字段字符串遵循与 name 属性相同的规则。这是一个可选属性。有时用于识别包的成熟度（“stable”、“testing”……），但通常不需要，包的成熟度最好通过将它们放入不同的服务器存储库来管理。

可以在命令行中使用 --channel=<mychannel> 指定通道。如果指定了通道，则还必须指定用户，因此包引用始终是完整的，如 pkg/version@user/channel。

元数据 ¶

可选元数据，如许可证、描述、作者等。大多数情况下不需要，但包含元数据可能很有用。

描述 ¶

这是一个可选但推荐的文本字段，包含包的描述以及可能对消费者有用的任何信息。第一行可能用作包的简短描述。

class HelloConan(ConanFile):
    name = "hello"
    version = "0.1"
    description = """This is a Hello World library.
                    A fully featured, portable, C++ library to say Hello World in the stdout,
                    with incredible iostreams performance"""

许可证 ¶

目标源代码和二进制文件的许可证，即被打包的代码，而不是 conanfile.py 本身。可以包含多个逗号分隔的许可证。它是一个文本字符串，因此可以包含任何文本，但强烈建议开源项目的配方使用 SPDX 标识符，来自 SPDX 许可证列表。

这将有助于那些希望自动化许可证兼容性检查的人，例如您的包的消费者，或者您自己（如果您的包有开源依赖项）。

class Pkg(ConanFile):
    license = "MIT"

作者 ¶

包的主要维护者/负责人，格式不限。这是一个可选属性。

class HelloConan(ConanFile):
    author = "John J. Smith (john.smith@company.com)"

主题 ¶

用于对相关包进行分组并描述代码内容的标签。在 ConanCenter 中用作搜索过滤器。可选属性。它应该是一个字符串元组。

class ProtocInstallerConan(ConanFile):
    name = "protoc_installer"
    version = "0.1"
    topics = ("protocol-buffers", "protocol-compiler", "serialization", "rpc")

主页 ¶

要打包的库的主页。

用于将配方链接到有关库本身的进一步说明，例如其功能的概述、文档、常见问题解答以及其他相关信息。

class EigenConan(ConanFile):
    name = "eigen"
    version = "3.3.4"
    homepage = "http://eigen.tuxfamily.org"

URL ¶

包存储库的 URL，即不一定是原始源代码的 URL。推荐但非强制性属性。

class HelloConan(ConanFile):
    name = "hello"
    version = "0.1"
    url = "https://github.com/conan-io/libhello.git"

依赖 ¶

依赖项简单声明的属性形式，如 requires、tool_requires。有关定义依赖项的更高级方法，请改用 requirements()、build_requirements() 方法。

requires ¶

主机上下文中的常规依赖项（如库）的字符串列表或元组。

class MyLibConan(ConanFile):
    requires = "hello/1.0", "otherlib/2.1@otheruser/testing"

您可以指定版本范围，语法使用方括号。

class HelloConan(ConanFile):
    requires = "pkg/[>1.0 <1.8]"

接受的表达式将是

表达式	范围内的版本	范围外的版本
[>=1.0 <2]	1.0.0, 1.0.1, 1.1, 1.2.3	0.2, 2.0, 2.1, 3.0
[<3.2.1]	0.1, 1.2, 2.4, 3.1.1	3.2.2
[>2.0]	2.1, 2.2, 3.1, 14.2	1.1, 1.2, 2.0

插入符号（caret）^ 和波浪号（tilde）~ 运算符基本上是下限和上限的紧凑表示。

范围 [~2.5.1] 可以写成 [>=2.5.1 <2.6.0]。
范围 [^1.2.3] 可以写成 [>=1.2.3 <2.0.0]。

通常，建议使用完整的表达式 [>=lower <upper] 而不是插入符号或波浪号的快捷方式，因为它对所有读者来说更明确、更易于理解该范围内的有效版本。

如果启用了预发布版本，例如定义配置 core.version_ranges:resolve_prereleases=True

表达式	范围内的版本	范围外的版本
[>=1.0 <2]	1.0.0-pre.1, 1.0.0, 1.0.1, 1.1, 1.2.3	0.2, 2.0-pre.1, 2.0, 2.1, 3.0
[<3.2.1]	0.1, 1.2, 1.8-beta.1, 2.0-alpha.2, 2.4, 3.1.1	3.2.1-pre.1, 3.2.1, 3.2.2, 3.3
[>2.0]	2.1-pre.1, 2.1, 2.2, 3.1, 14.2	1.1, 1.2, 2.0-pre.1, 2.0

另请参阅

请参阅版本范围表达式的教程部分。
请参阅 requirements() 方法文档。

tool_requires ¶

依赖项的字符串列表或元组。表示一个构建工具，如“cmake”。如果当前包存在预编译的二进制文件，则不会检索工具依赖项的二进制文件。它们不能冲突。

class MyPkg(ConanFile):
    tool_requires = "tool_a/0.2", "tool_b/0.2@user/testing"

这是添加 tool_requires 的声明式方法。请参阅 tool_requires() conanfile.py 方法，了解更灵活的添加方式。

build_requires ¶

build_requires 在 Conan 2 中用于提供与 Conan 1.X 语法的兼容性，但在 Conan 2 中不推荐使用 build_requires，并且在未来的 2.X 版本中将被弃用。请在您的 Conan 2 配方中使用 tool_requires 而不是 build_requires。

test_requires ¶

仅在主机上下文中使用的依赖项的字符串列表或元组。表示一个测试工具，如“gtest”。当当前包从源代码构建时使用。它们不会将信息传播给下游消费者。如果当前包存在预编译的二进制文件，则不会检索测试依赖项的二进制文件。它们不能冲突。

class MyPkg(ConanFile):
    test_requires = "gtest/1.17.0", "other_test_tool/0.2@user/testing"

这是添加 test_requires 的声明式方法。请参阅 test_requires() 方法，了解更灵活的添加方式。

python_requires ¶

此类属性允许定义对另一个 Conan 配方的依赖关系并重用其代码。其基本语法是

from conan import ConanFile

class Pkg(ConanFile):
    python_requires = "pyreq/0.1@user/channel"  # recipe to reuse code from

    def build(self):
        self.python_requires["pyreq"].module # access to the whole conanfile.py module
        self.python_requires["pyreq"].module.myvar  # access to a variable
        self.python_requires["pyreq"].module.myfunct()  # access to a global function
        self.python_requires["pyreq"].path # access to the folder where the reused file is

在 Python requires 中阅读有关此属性的更多信息。

python_requires_extend ¶

此类属性定义了一个或多个将在运行时注入为配方类基类的类。这些类的每个类的语法都应为字符串，如 pyreq.MyConanfileBase，其中 pyreq 是 python_requires 的名称，MyConanfileBase 是要使用的类的名称。

from conan import ConanFile

class Pkg(ConanFile):
    python_requires = "pyreq/0.1@user/channel", "utils/0.1@user/channel"
    python_requires_extend = "pyreq.MyConanfileBase", "utils.UtilsBase"  # class/es to inject

源代码 ¶

exports ¶

字符串列表或元组，包含应导出并与 *conanfile.py* 文件一起存储的文件名或 fnmatch 模式，以使配方能够正常工作：配方将导入的其他 python 文件、要读取的包含数据的文本文件……

例如，如果我们有一些我们希望配方使用的 python 代码，位于 helpers.py 文件中，并且有一个我们想要读取和显示的文本文件 *info.txt*，我们将这样做：

exports = "helpers.py", "info.txt"

排除模式也是可能的，带有 ! 前缀。

exports = "*.py", "!*tmp.py"

另请参阅

查看 export() conanfile.py 方法。.

exports_sources ¶

字符串列表或元组，包含应导出并可用于生成包的文件名或 fnmatch 模式。与 exports 属性不同，这些文件不应被 conanfile.py Python 代码使用，而是用于编译库或生成最终包。而且，由于其目的，这些文件仅在请求的二进制文件不可用或用户强制 Conan 从源代码编译时才会被检索。

这是获取源代码的 source() 方法的替代方法。当我们不打包第三方库并且配方与 C/C++ 项目在一起时使用。

exports_sources = "include*", "src*"

排除模式也是可能的，带有 ! 前缀。

exports_sources = "include*", "src*", "!src/build/*"

注意，如果配方定义了 layout() 方法并指定了 self.folders.source = "src"，这不会影响 exports_sources 中的文件被复制到哪里。它们将被复制到基础源文件夹。因此，如果您想替换进入 source() 方法的某个文件，您需要从父文件夹显式复制它，甚至更好的是，从 self.export_sources_folder 复制。

import os, shutil
from conan import ConanFile
from conan.tools.files import save, load

class Pkg(ConanFile):
    ...
    exports_sources = "CMakeLists.txt"

    def layout(self):
        self.folders.source = "src"
        self.folders.build = "build"

    def source(self):
        # emulate a download from web site
        save(self, "CMakeLists.txt", "MISTAKE: Very old CMakeLists to be replaced")
        # Now I fix it with one of the exported files
        shutil.copy("../CMakeLists.txt", ".")
        shutil.copy(os.path.join(self.export_sources_folder, "CMakeLists.txt"), ".")

另请参阅

查看 export_sources() conanfile.py 方法。.

conan_data ¶

只读属性，一个字典，其中包含位于 *conanfile.py* 旁边的 conandata.yml 文件格式中提供的键和值。此 YAML 文件会自动随配方导出，并在加载配方时自动加载。

您可以在 *conandata.yml* 文件中声明信息，然后在配方的任何方法中访问它。例如，一个关于源代码的 *conandata.yml* 文件如下所示：

sources:
  "1.1.0":
    url: "https://www.url.org/source/mylib-1.0.0.tar.gz"
    sha256: "8c48baf3babe0d505d16cfc0cf272589c66d3624264098213db0fb00034728e9"
  "1.1.1":
    url: "https://www.url.org/source/mylib-1.0.1.tar.gz"
    sha256: "15b6393c20030aab02c8e2fe0243cb1d1d18062f6c095d67bca91871dc7f324a"

def source(self):
    get(self, **self.conan_data["sources"][self.version])

source_buildenv ¶

布尔属性，用于选择在运行 source() 方法时注入 VirtualBuildEnv 生成的环境。

将此属性设置为 True（默认值 False）将在执行 source() 方法时注入来自工具要求的 VirtualBuildEnv 生成的环境。

 class MyConan:
    name = "mylib"
    version = "1.0.0"
    source_buildenv = True
    tool_requires = "7zip/1.2.0"

    def source(self):
        get(self, **self.conan_data["sources"][self.version])
        self.run("7z x *.zip -o*")  ## Can run 7z in the source method

二进制模型 ¶

定义包二进制模型的重要属性，例如哪些设置、选项、包类型等会影响最终打包的二进制文件。

package_type ¶

可选。声明 package_type 将有助于 Conan

为每个依赖项更好地选择默认的 package_id_mode，即依赖项的更改如何影响当前包的 package_id。
从依赖项中应传播给消费者哪些信息，例如头文件、库、运行时信息。请参阅此处了解基于 package_type 信息传播哪些特征。

有效值为

application：包是一个应用程序。
library：包是一个通用库。它将尝试确定库的类型（来自 shared-library、static-library、header-library），读取 self.options.shared（如果已声明）和 self.options.header_only。
shared-library：包是一个共享库。
static-library：包是一个静态库。
header-library：包是一个仅头文件库。
build-scripts：包仅包含构建脚本。
python-require：包是一个 python require。
unknown：包的类型未知。

请注意，包之间的关系可能并不总是定义明确，并且可能导致错误，例如，build-scripts 不能有常规的 requires 依赖项来编译库，并且不知道如何通过旨在用作 tool_requires 的东西来传播它们。如果某个包想要同时使用一些构建脚本并链接到一个给定的库，它应该定义一个 tool_requires() 到 build-scripts 包，并定义一个常规的 requires() 到编译的库。

settings ¶

字符串列表，包含配方所需的顶层设置（来自 settings.yml），因为：- 它们用于构建（例如：if self.settings.compiler == “gcc”）- 它们会影响 package_id。如果声明的设置值发生更改，则 package_id 必须不同。

最常见的是声明

settings = "os", "compiler", "build_type", "arch"

一旦配方被 Conan 加载，settings 就会被处理，并且可以在配方中读取它们，也可以读取子设置。

settings = "os", "arch"

def build(self):
    if self.settings.compiler == "gcc":
        if self.settings.compiler.cppstd == "gnu20":
            # do some special build commands

如果您尝试访问不存在的设置，例如 msvc 设置的 self.settings.compiler.libcxx，Conan 将会失败并提示 libcxx 对于该编译器不存在。

如果要安全地检查设置值，可以使用 get_safe() 方法。

def build(self):
    # Will be None if doesn't exist (not declared)
    arch = self.settings.get_safe("arch")
    # Will be None if doesn't exist (doesn't exist for the current compiler)
    compiler_version = self.settings.get_safe("compiler.version")
    # Will be the default version if the return is None
    build_type = self.settings.get_safe("build_type", default="Release")

如果该设置或子设置不存在且没有分配默认值，get_safe() 方法将返回 None。

也可以使用 possible_values() 方法检查 settings.yml 中定义的可能值。

def generate(self):
    # Print if Android exists as OS in the whole settings.yml
    is_android = "Android" in self.settings.possible_values()["os"]
    self.output.info(f"Android in settings.yml: {is_android}")
    # Print the available versions for the compiler used by the HOST profile
    compiler_versions = self.settings.compiler.version.possible_values()
    self.output.info(f"[HOST] Versions for {str(self.settings.compiler)}:  {', '.join(compiler_versions)}")
    # Print the available versions for the compiler used by the BUILD profile
    compiler_versions = self.settings_build.compiler.version.possible_values()
    self.output.info(f"[BUILD] Versions for {str(self.settings_build.compiler)}:  {', '.join(compiler_versions)}")

如上所示，执行 self.settings.possible_values() 将返回整个 settings.yml 作为类似 Python 字典的对象，而执行 self.settings.compiler.version.possible_values() 则会返回消费者使用的编译器可用版本。

如果要安全地删除设置，可以使用 rm_safe() 方法。例如，在 configure() 方法中，C 库的典型模式是：

def configure(self):
    self.settings.rm_safe("compiler.libcxx")
    self.settings.rm_safe("compiler.cppstd")

另请参阅

options ¶

字典，其中包含仅影响当前配方的特征，键是选项名称，值是可以选择的不同值的列表。默认情况下，选项中的任何值更改都会更改 package_id。请参阅 default_options 和 default_build_options 字段来定义选项的默认值。

每个选项的值可以是类型化的，也可以是纯字符串（"value"、True、42……）。

有两个特殊值：

None：允许选项具有 None 值（未指定）而不会出错。
"ANY"：对于可以接受任何值的选项，不受集合限制。

class MyPkg(ConanFile):
    ...
    options = {
        "shared": [True, False],
        "option1": ["value1", "value2"],
        "option2": ["ANY"],
        "option3": [None, "value1", "value2"],
        "option4": [True, False, "value"],
}

一旦配方被 Conan 加载，options 就会被处理，并且可以在配方中读取它们。您还可以使用 .get_safe() 方法（请参阅 settings 属性）来避免 Conan 引发异常，如果选项不存在。

class MyPkg(ConanFile):
    options = {"shared": [True, False]}

    def build(self):
        if self.options.shared:
            # build the shared library
        if self.options.get_safe("foo", True):
            pass

在布尔表达式中，例如 if self.options.shared。

对于 True、"True" 和 "true" 的值等于 True，以及任何其他在 Python 代码中会以相同方式评估的值。
对于 False、"False" 和 "false" 的值，以及空字符串、0 和 "0"，等于 False，正如预期的那样。

请注意，使用 is 进行比较始终为 False，因为类型不同，因为它被封装在 Python 类中。

如果要安全地删除选项，可以使用 rm_safe() 方法。例如，在 config_options() 方法中，Windows 库的典型模式是：

def config_options(self):
    if self.settings.os == "Windows":
        self.options.rm_safe("fPIC")

另请参阅

default_options ¶

default_options 属性定义了当前配方和任何要求的选项的默认值。此属性应定义为 Python 字典。

class MyPkg(ConanFile):
    ...
    requires = "zlib/1.2.8", "zwave/2.0"
    options = {"build_tests": [True, False],
                "option2": "ANY"}
    default_options = {"build_tests": True,
                        "option1": 42,
                        "z*:shared": True}

您还可以使用“<reference_pattern>: option_name”为您的依赖项的选项分配默认值，其中 reference_pattern 是一个有效的 name/version 或任何带有 * 的模式，如上面的示例。

警告

在配方中定义选项值没有强保证，请参阅关于依赖项选项值的常见问题解答。定义选项值的推荐方法是在配置文件中。

您也可以在 configure() 方法中将选项有条件地设置为最终值，而不是使用 default_options。

class OtherPkg(ConanFile):
    settings = "os", "arch", "compiler", "build_type"
    options = {"some_option": [True, False]}
    # Do NOT declare 'default_options', use 'config_options()'

    def configure(self):
        if self.options.some_option == None:
            if self.settings.os == 'Android':
                self.options.some_option = True
            else:
                self.options.some_option = False

请注意，如果在 configure() 方法中分配了值，则无法覆盖它。

另请参阅

config_options() 方法。.

配方可以尝试定义其依赖项选项值的两种不同方式。使用 default_options = {"mypkg/*:myoption", 123}，当前配方可以为 mypkg 的 myoption 定义 123 值。这种为依赖项定义选项的方式存在一些限制。

任何其他下游配方，如果为 mypkg 定义了相同的选项，将优先于当前配方的 123 值。配置文件或命令行中的任何定义也将优先。配方 default_options 的优先级最低。如果配方完全无法与某些依赖项选项一起工作，那么配方可以检查并引发 ConanInvalidConfiguration 错误。
任何依赖于 mypkg 的同级包也将定义其选项，并且它将是唯一被考虑的。换句话说，第一次由任何其他包要求 mypkg 时，它将“冻结”其当前分配的选项值。后来依赖于 mypkg 的任何其他包（形成依赖图中的菱形结构）都不会对 mypkg 选项产生任何影响。只有第一个要求它的包才会。

定义选项值的第二种方法是将其定义为 important!。

警告

语法 important! 是实验性的，可能会随时更改或删除。

配方可以定义其依赖项选项为 important!，语法为 default_options = {"mypkg/*:myoption!", 123}。这意味着 mypkg 的 myoption 不会被其他下游包、配置文件或命令行（通过常规选项定义，如 -o *:myoption=234）覆盖。

但在两种情况下，这仍然不会定义依赖项的最终值：

如果任何下游配方、命令行或配置文件也使用 myoption! 语法，那么它也将优先并覆盖上游值。
如果存在其他包首先要求 mypkg，那么在那个时候定义的值仍将优先。

总的来说，建议在 profile 文件中定义选项值，而不是在配方中，因为配方内定义可能更复杂，尤其是在复杂的依赖关系图中。

default_build_options ¶

default_build_options 属性定义了构建上下文中的选项的默认值，通常用于定义 tool_requires 的选项。

from conan import ConanFile
class Consumer(ConanFile):
    default_options = {"protobuf/*:shared": True}
    default_build_options = {"protobuf/*:shared": False}
    def requirements(self):
        self.requires("protobuf/1.0")
    def build_requirements(self):
        self.tool_requires("protobuf/1.0")

options_description ¶

options_description 属性是一个可选属性，可以定义为字典形式，其中键是选项名称，值是选项的文本描述。此属性对于提供有关每个选项的功能和用途的附加信息非常有用，特别是当选项不自明或具有复杂或特殊行为时。

每个字典条目的格式应为：

键：选项名称。必须是字符串，并且必须与 options 字典中的某个键匹配。
值：选项的描述。必须是字符串，长度可以任意。

例如：

class MyPkg(ConanFile):
    ...
    options = {"option1": [True, False],
               "option2": "ANY"}

    options_description = {
        "option1": "Describe the purpose and functionality of 'option1'. ",
        "option2": "Describe the purpose and functionality of 'option2'. ",
    }

languages ¶

警告

此功能是实验性的，可能会发生重大更改。有关更多信息，请参阅 Conan 稳定性部分。

从 Conan 2.4 开始，conanfile.py 配方属性 languages 可用于定义此包涉及的编程语言。目前 C 和 C++ 是可能的值。例如，一个纯 C 包将定义如下：

class ZLib(ConanFile):
    languages = "C"

可以定义多种语言，例如 languages = "C", "C++"，当一个包从 C 和 C++ 源代码构建时，这是正确的定义。

关于 languages 的定义，将发生以下情况：

如果未定义 languages 或未将 C 声明为语言，则在包 configure() 时会自动删除 compiler.cstd 子集（以实现向后兼容）。
如果定义了 languages，但它不包含 C++，则在包 configure() 时会自动删除 compiler.cppstd 和 compiler.libcxx 子集。

info ¶

仅在 package_id() 方法中使用的对象。

package_id 方法用于控制包的唯一 ID。

def package_id(self):
    self.info.clear()

self.info.clear() 方法会从 package_id 计算中删除所有设置、选项、依赖项（requires、tool_requires、python_requires）和配置（conf），因此 package_id 将始终产生相同的二进制文件，而与这些因素无关。这对于仅头文件的库来说很常见，因为打包的工件（文件）始终是相同的。

package_id_{embed,non_embed,python,unknown}_mode, build_mode ¶

package_id_embed_mode, package_id_non_embed_mode, package_id_python_mode, package_id_unknown_mode 是可以在配方中定义的类属性，用于定义它们对消费者 package_id 的影响，当它们被用作 requires 时。

build_mode（实验性）是一个类属性，它会影响当这些消费者使用此依赖项作为 tool_requires 时。

from conan import ConanFile

class Pkg(ConanFile):
    name = "pkg"
    version = "1.0.0"
    # They are not mandatory, and it is not necessary to define all
    package_id_embed_mode = "full_mode"
    package_id_non_embed_mode = "patch_mode"
    package_id_unknown_mode = "minor_mode"
    package_id_python_mode = "major_mode"
    build_mode = "patch_mode"  # (experimental) when used as tool_requires

通常，Conan 的默认设置是很好的，并且允许用户很好地控制消费者何时需要从源代码重新构建。此外，Conan 的默认设置可以在 global.conf 文件中全局更改（它们应该为所有用户、CI 等全局更改），通过 core.package_id:xxxx 配置。配方内属性定义对于定义与默认值不同的行为很有用。

可能的值是（遵循 MAJOR.MINOR.PATCH 的 semver 定义）：

patch_mode：包的新补丁、次要版本和主版本将需要消费者的新二进制文件（新的 package_id）。新的配方修订版将不需要消费者的新二进制文件。例如，如果我们创建一个新的 pkg/1.0.1 版本，并且某个消费者具有 requires = "pkg/[>=1.0 <2.0]"，那么该消费者将构建一个新的二进制文件来匹配这个新的 1.0.1 版本。但是，如果我们仅更改配方，生成新的 recipe_revision，那么消费者将不需要构建新的二进制文件。
minor_mode：此包的次要版本和主版本更新将需要消费者的新二进制文件。新的补丁版本和新的修订版将不需要消费者的新二进制文件。这是“non-embed-mode”的默认值，因为它允许用户精细控制何时重新构建内容。
major_mode：只有主版本更新才需要新的二进制文件。任何其他修改和新版本都将不需要消费者的新二进制文件。
full_mode：此包的完整标识符，包括 pkgname/version@user/channel#recipe_revision:package_id 将在消费者的 package_id 中使用，因此对于此包的每次更改（无论是源代码还是配置的更改都会产生不同的 recipe_revision 或 package_id），都需要构建消费者的新二进制文件。这是“embed-mode”的默认设置。
unrelated_mode：此包中的任何更改永远不会导致消费者中的新二进制文件。
revision_mode：使用 pkgname/version@user/channel#recipe_revision 在消费者的 package_id 中，即完整的引用，但不包括依赖项的 package_id。
semver_mode：如果版本为 >=1.0，则等同于 major_mode；如果版本为 <1.0，则等同于 patch_mode（或具有超过 3 位数字的完整版本）。

这 4 个不同的属性是：

package_id_embed_mode：定义“嵌入”情况的模式，即共享库链接静态库，应用程序链接静态库，应用程序或库链接仅头文件的库。此模式的默认值为 full_mode。
package_id_non_embed_mode：定义“非嵌入”情况的模式，即共享库链接另一个共享库，静态库链接另一个静态库，应用程序可执行文件链接共享库。此模式的默认值为 minor_mode。
package_id_unknown_mode：定义包之间关系未知时的模式。如果无法推断包类型，因为没有定义 shared 或 header_only 选项，或者因为未定义 package_type，那么将使用此模式。此模式的默认值为 semver_mode（类似于 Conan 1.X 的行为）。
package_id_python_mode：定义 python_requires 的消费者的模式。默认情况下为 minor_mode，强烈建议使用此默认值，并且不要定义 package_id_python_mode。此属性是为了完整性和特殊情况（如临时迁移）而提供的。
build_mode：（实验性）定义消费者将此依赖项用作 tool_requires 时的模式。默认值为 None，这意味着 tool_requires 不直接影响其消费者的 package_id。启用此 build_mode 会为 tool_requires 引入更强的依赖关系，在更多情况下需要这些依赖项来解析消费者的 package_id。

另请参阅

有关 Conan 二进制模型的完整视图，请参阅二进制模型参考。

构建 ¶

generators ¶

生成器名称的列表或元组。

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

生成器也可以在 generate() 方法中显式实例化。

from conan.tools.cmake import CMakeToolchain

class MyLibConan(ConanFile):
    ...

    def generate(self):
        tc = CMakeToolchain(self)
        tc.generate()

build_policy ¶

控制当前包在 conan install 期间何时构建。允许的值为：

"missing"：如果找不到二进制文件，Conan 将从源代码构建它。
"never"：此包不能从源代码构建，它始终使用 conan export-pkg 创建。
None（默认值）：除非在命令行中指定了策略（例如 --build=foo*），否则将不会构建此包。
class PocoTimerConan(ConanFile): build_policy = "missing"

win_bash ¶

当 True 时，它会在 Windows 子系统中启用新的 bash 运行机制。

from conan import ConanFile

class FooRecipe(ConanFile):
    ...
    win_bash = True

它也可以声明为基于任何条件的 property。

from conan import ConanFile

class FooRecipe(ConanFile):
    ...


    @property
    def win_bash(self):
        return self.settings.arch == "armv8"

win_bash_run ¶

当 True 时，它会在 "run" 作用域中启用在 bash shell 中运行命令。

from conan import ConanFile

class FooRecipe(ConanFile):

    ...

    win_bash_run = True
    def build(self):
        self.run(cmd, scope="run")  # will run <cmd> inside bash

文件夹和布局 ¶

source_folder ¶

源代码所在的文件夹。该路径是通过将基本目录（在缓存中运行时是缓存目录，在本地运行时是 output folder）与 layout() 方法中声明的 folders.source 值连接而成的。

请注意，当在缓存中运行时，source_folder 的基本目录将指向构建的基本目录，除非 no_copy_source 设置为 True。但无论如何，它总是指向源代码所在的正确文件夹。

export_sources_folder ¶

值取决于您访问它的方法。

在 source(self) 中：指向基础源文件夹（这意味着 self.source_folder，但不考虑 layout() 方法中声明的 folders.source）。声明的 exports_sources 始终复制到该基础源文件夹。
在 exports_sources(self) 中：指向缓存中必须将导出源代码复制到的文件夹。

另请参阅

build_folder ¶

用于构建源代码的文件夹。该路径是通过将基本目录（在缓存中运行时是缓存目录，在本地运行时是 output folder）与 layout() 方法中声明的 folders.build 值连接而成的。

generators_folder ¶

应在 generate() 方法中生成文件的文件夹。该路径来自布局的 self.folders.generators 属性。

package_folder ¶

用于将最终工件复制到二进制包的文件夹。在本地缓存中，为每个不同的包 ID 创建一个包文件夹。

self.package_folder 最常见的用法是在 package() 方法中 copy 文件。

import os
from conan import ConanFile
from conan.tools.files import copy

class MyRecipe(ConanFile):
    ...

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

recipe_folder ¶

配方 *conanfile.py* 存储的文件夹，无论是在本地文件夹还是在缓存中。这对于访问与配方一起导出的文件，或者在 export(self) 和 export_sources(self) 方法中导出文件的源文件夹很有用。

self.recipe_folder 最常见的用法是在 export(self) 和 export_sources(self) 方法中，作为我们从中复制文件的文件夹。

from conan import ConanFile
from conan.tools.files import copy

class MethodConan(ConanFile):
    exports = "file.txt"
    def export(self):
        copy(self, "LICENSE.md", self.recipe_folder, self.export_folder)

recipe_metadata_folder ¶

self.recipe_metadata_folder（实验性）可以在 export()、export_sources() 和 source() 方法中用于保存或复制配方元数据文件。有关更多信息，请参阅元数据部分。

package_metadata_folder ¶

self.package_metadata_folder（实验性）可以在 generate()、build() 和 package() 方法中用于保存或复制包元数据文件。有关更多信息，请参阅元数据部分。

no_copy_source ¶

no_copy_source 属性告诉配方源代码将不会从 source_folder 复制到 build_folder。这主要是为了优化大型源代码库或仅头文件的包，以避免额外的复制。

如果激活 no_copy_source=True，那么源代码在配置或构建脚本中绝对不能被修改，因为源代码将在所有构建之间共享。

配方应始终使用 self.source_folder 属性，当 no_copy_source=False 时，它将指向 build 文件夹；当 no_copy_source=True 时，它将指向 source 文件夹。

另请参阅

阅读仅头文件包部分以获取使用 no_copy_source 属性的示例。

test_package_folder ¶

test_package_folder 类属性允许在配方中为 conan create 命令定义一个不同的默认 test_package 文件夹。当运行 conan create 时，在包在缓存中创建后，它将查找 test_package 文件夹，或 --test-folder=xxx 参数指定的文件夹，并启动包测试。

此属性允许更改该默认名称。

import os
from conan import ConanFile

class Pkg(ConanFile):
    test_package_folder = "my/test/folder"

它允许定义任何文件夹，始终相对于 conanfile.py 的位置。

布局 ¶

folders ¶

folders 属性只能在 layout() 方法中设置。请参阅 layout() 方法文档以了解有关此属性的更多信息。

cpp ¶

存储包消费者所需的所有信息（包括目录、库名称、库路径……）的对象。适用于缓存中的可编辑包和常规包。它仅在 layout() 方法中可用。

self.cpp.package：对于从 Conan 缓存使用的常规包。与在 package_info() 方法中声明 self.cpp_info 相同。
self.cpp.source：对于“可编辑”包，用于描述 self.source_folder 下的工件。
self.cpp.build：对于“可编辑”包，用于描述 self.build_folder 下的工件。

cpp 属性只能在 layout() 方法中设置。请参阅 layout() 方法文档以了解有关此属性的更多信息。

layouts ¶

layouts 属性只能在 layout() 方法中设置。请参阅 layout() 方法文档以了解有关此属性的更多信息。

layouts 属性包含有关环境变量和 conf 的信息，这些信息是路径相关的，因此在包处于可编辑模式或在缓存中时，它将包含不同的值。 layouts 子属性是：

self.layouts.build：与相对 self.folders.build 相关的信息。
self.layouts.source：与相对 self.folders.source 相关的信息。
self.layouts.package：与最终 package_folder 相关的信息。

它们每个都将包含：

buildenv_info：消费者（等同于 package_info() 方法中的 self.buildenv_info）的构建环境变量信息。
runenv_info：消费者（等同于 package_info() 方法中的 self.runenv_info）的运行时环境变量信息。
conf_info：消费者（等同于 package_info() 方法中的 self.conf_info）的配置信息。注意，只有当此包是直接 tool_require 时，它才会自动传播到消费者的 self.conf。

例如，如果我们有一个包含 AndroidNDK 的 androidndk 配方，并且我们希望该配方处于“可编辑”模式，那么在创建包之前，需要知道 AndroidNDK 在本地的位置。

import os
from conan import ConanFile
from conan.tools.files import copy

class AndroidNDK(ConanFile):

    def layout(self):
        # When developing in user space it is in a "mybuild" folder (relative to current dir)
        self.layouts.build.conf_info.define_path("tools.android:ndk_path", "mybuild")
        # but when packaged it will be in a "mypkg" folder (inside the cache package folder)
        self.layouts.package.conf_info.define_path("tools.android:ndk_path", "mypkg")

    def package(self):
        copy(self, "*", src=os.path.join(self.build_folder, "mybuild"),
             dst=os.path.join(self.package_folder, "mypkg"))

供消费者使用的包信息 ¶

cpp_info ¶

与在 layout() 方法中使用 self.cpp.package 相同。如果您需要读取 package_folder 来定位已定位的工件，则使用此方法。

另请参阅

CppInfo 模型。

重要

此属性仅在 package_info() 方法中定义，在其他地方为 None。

buildenv_info ¶

对于依赖的配方，声明的环境变量将在构建过程中存在。应仅在 package_info() 方法中填充。

重要

此属性仅在 package_info() 方法中定义，在其他地方为 None。

def package_info(self):
    self.buildenv_info.append_path("PATH", self.package_folder)

另请参阅

请参阅 Environment 对象的参考，了解如何填充 self.buildenv_info。

runenv_info ¶

对于依赖的配方，声明的环境变量将在运行时存在。应仅在 package_info() 方法中填充。

重要

此属性仅在 package_info() 方法中定义，在其他地方为 None。

def package_info(self):
    self.runenv_info.define_path("RUNTIME_VAR", "c:/path/to/exe")

另请参阅

请参阅 Environment 对象的参考，了解如何填充 self.runenv_info。

conf_info ¶

要传递给依赖的配方的配置变量。应仅在 package_info() 方法中填充。

class Pkg(ConanFile):
    name = "pkg"

    def package_info(self):
        self.conf_info.define("tools.build:verbosity", "debug")
        self.conf_info.get("tools.build:verbosity")  # == "debug"
        self.conf_info.append("user.myconf.build:ldflags", "--flag3")  # == ["--flag1", "--flag2", "--flag3"]
        self.conf_info.update("tools.microsoft.msbuildtoolchain:compile_options", {"ExpandAttributedSource": "false"})
        self.conf_info.unset("tools.microsoft.msbuildtoolchain:compile_options")
        self.conf_info.remove("user.myconf.build:ldflags", "--flag1")  # == ["--flag0", "--flag2", "--flag3"]
        self.conf_info.pop("tools.system.package_manager:sudo")

另请参阅

在此处阅读 self.conf_info 的完整参考。

generator_info ¶

警告

此功能是实验性的，可能会发生重大更改。有关更多信息，请参阅 Conan 稳定性部分。

要传递给依赖的配方的生成器。应仅在 package_info() 方法中填充，默认值为 None。

另请参阅

在此处查看示例用法，以及self.generator_info 的完整参考。

已弃用 ¶

此属性声明了配方已弃用，导致每次使用配方时都会发出用户友好的警告消息。

例如，以下代码

from conan import ConanFile

class Pkg(ConanFile):
    name = "cpp-taskflow"
    version = "1.0"
    deprecated = True

可能会发出像这样的risk警告

Deprecated
    cpp-taskflow/1.0

WARN: risk: There are deprecated packages in the graph

可选地，该属性可以指定建议的替代品的名称。

from conan import ConanFile

class Pkg(ConanFile):
    name = "cpp-taskflow"
    version = "1.0"
    deprecated = "Not secure, use better taskflow>1.2.3"

这将发出像这样的risk警告

Deprecated
    cpp-taskflow/1.0: Not secure, use better taskflow>1.2.3

WARN: risk: There are deprecated packages in the graph

如果该属性的值评估为False，则不会打印警告。

提供 ¶

此属性声明配方提供与其他配方相同的功能。该属性通常在两个或多个库实现相同 API 以防止链接时和运行时冲突（ODR 违规）时需要。一个典型的情况是分叉的库。一些例子是

如果 Conan 在单个图中遇到两个或多个提供相同功能的库，它将引发错误。

At least two recipes provides the same functionality:
- 'libjpeg' provided by 'libjpeg/9d', 'libjpeg-turbo/2.0.5'

属性值应该是包含配方名称的字符串或此类配方名称的元组。

例如，要声明libjpeg-turbo配方提供与libjpeg配方相同的功能，可以使用以下代码

from conan import ConanFile

class LibJpegTurbo(ConanFile):
    name = "libjpeg-turbo"
    version = "1.0"
    provides = "libjpeg"

要声明一个配方同时提供多个不同配方功能，可以使用以下代码

from conan import ConanFile

class OpenBLAS(ConanFile):
    name = "openblas"
    version = "1.0"
    provides = "cblas", "lapack"

如果省略该属性，则假定该属性的值等于当前包的名称。因此，对于libjpeg配方声明它提供libjpeg来说是多余的，Conan 已经隐含地假定了这一点。

其他 ¶

依赖项 ¶

Conan 配方通过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

另请参阅

在此处阅读 self.dependencies 的完整参考。

子图 ¶

(实验性) 配方的只读依赖项图。dependencies属性应用于访问配方的依赖项，因为此属性旨在传递给其他 Conan API，并为高级用法（如SBOM 生成）公开。

conf ¶

在self.conf属性中，我们可以找到配置文件中的所有 conf 条目[conf]部分。以及来自第一级工具要求中声明的self.conf_info条目。配置文件条目具有优先权。

from conan import ConanFile

class MyConsumer(ConanFile):

  tool_requires = "my_android_ndk/1.0"

  def generate(self):
      # This is declared in the tool_requires
      self.output.info("NDK host: %s" % self.conf.get("tools.android:ndk_path"))
      # This is declared in the profile at [conf] section
      self.output.info("Custom var1: %s" % self.conf.get("user.custom.var1"))

注意

conf属性是**只读**属性。它只能在配置文件和命令行中定义，但绝不应由配方设置。配方只能通过self.conf.get()方法读取其值。

输出 ¶

输出内容 ¶

使用self.output属性将内容打印到输出。

self.output.success("This is good, should be green")
self.output.info("This is neutral, should be white")
self.output.warning("This is a warning, should be yellow")
self.output.error("Error, should be red")

其他输出方法是可用的，并且您可以使用不同的颜色产生不同的输出。有关可用输出方法的列表，请参阅输出文档。

revision_mode ¶

此属性允许每个配方声明如何计算配方本身的修订版本。它可以取三种不同的值：

"hash" (默认): Conan 将使用配方清单的校验和哈希来计算配方的修订版本。
"scm": 如果项目位于 Git 存储库中，提交 ID 将被用作配方修订版本。如果没有存储库，它将引发错误。
"scm_folder": 此配置适用于您拥有单体存储库项目，但仍希望使用scm修订版本的情况。在这种情况下，导出的conanfile.py的修订版本将对应于其所在文件夹的提交 ID。此方法允许在同一个 Git 存储库中存在多个conanfile.py文件，每个文件在其不同的修订版本下导出。

当选择scm或scm_folder时，将使用 Git 提交，但默认情况下存储库必须是干净的，否则很可能会有未提交的更改，并且构建将不可重现。因此，如果存储库中有脏文件，Conan 将引发错误。如果存储库中有不属于配方或包的脏文件，则可以使用core.scm:excluded配置排除它们，该配置是用于排除的模式列表 (fnmatch)。

upload_policy ¶

控制当前已构建的二进制文件何时上传或不上传。

"skip": 预编译的二进制文件不会上传。这对于仅下载和解压缩大型文件的“安装程序”包（例如 android-ndk）非常有用，并且与build_policy = "missing"一起使用非常有用。
class Pkg(ConanFile): upload_policy = "skip"

required_conan_version ¶

配方可以定义一个模块级别的required_conan_version，它定义了一个有效版本的 Conan 版本范围，这些版本可以加载和理解当前的conanfile.py。语法是

from conan import ConanFile

required_conan_version = ">=2.0"

class Pkg(ConanFile):
    pass

允许使用版本范围，就像在requires中一样。还有一个global.conf文件core:required_conan_version配置，它可以定义一个全局的最小、最大或精确的 Conan 版本来运行，这对于维护开发团队和 CI 机器使用所需的版本范围非常方便。

implements ¶

列表用于定义一系列 Conan 将自动处理的选项配置。这对于避免大多数配方中倾向于重复的样板代码特别有用。语法如下：

from conan import ConanFile

class Pkg(ConanFile):
    implements = ["auto_shared_fpic", "auto_header_only", ...]

目前，这些是 Conan 提供的自动实现：

"auto_shared_fpic": 自动管理 fPIC 和 shared 选项。添加此实现将在configure和config_options步骤中生效，前提是这些方法未在配方中明确定义。
"auto_header_only": 自动管理包 ID 清除设置。添加此实现将在package_id步骤中生效，前提是该方法未在配方中明确定义。

警告

这是 2.0 专属功能，在 1.X 中无效。

别名 ¶

警告

虽然别名在 Conan 2 中技术上仍可使用，但不建议使用它们，并且它们可能会在未来的版本中被完全移除。鼓励用户适应更新的版本管理功能，以获得更标准化、更高效的包管理体验。

在 Conan 2 中，alias属性仍然是配方的一部分，允许用户为包版本定义一个别名。通常，您可以使用conan new命令与alias模板一起创建一个别名，并使用 conan export 导出配方。

$ conan new alias -d name=mypkg -d version=latest -d target=1.0
$ conan export .

请注意，在要求别名时，您必须将版本放在括号()中，以明确声明将别名作为需求使用。

class Consumer(ConanFile):

    ...
    requires = "mypkg/(latest)"
    ...

extension_properties ¶

extensions_properties属性是一个字典，用于将信息从配方定义并传递给 Conan 扩展。

目前，已定义的属性是compatibility_cppstd和compatibility_cstd，它们允许禁用默认的 compatibility.py 扩展的行为，该扩展认为使用不同compiler.cppstd和compiler.cstd值构建的二进制文件是 ABI 兼容的。要为此包禁用此行为，可以使用以下方法：

class Pkg(ConanFile):
    extension_properties = {"compatibility_cppstd": False}

如果需要有条件地执行此操作，也可以在配方compatibility()方法中定义其值。

class Pkg(ConanFile):

    def compatibility(self):
        self.extension_properties = {"compatibility_cppstd": False}

注意

extension_properties的值默认不会从依赖项传递到使用者，但可以通过迭代self.dependencies并检查其extension_properties的所需值来手动传播。