属性

包引用

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

name

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

  • 最少 2 个，最多 101 个字符（尽管建议使用较短的名称）。

  • 匹配以下正则表达式 ^[a-z0-9_][a-z0-9_+.-]{1,100}$：因此以字母数字或 _ 开头，

    然后是 1 到 100 个字符，字符可以是字母数字、_、+、. 或 -。

名称仅在将 recipe export 到本地缓存时（export, export-pkg

和 create 命令）是必需的，如果在命令行中未使用 --name=<pkgname> 定义。

version

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

版本仅在将 recipe export 到本地缓存时（export, export-pkg 和 create 命令）是严格必需的，如果在命令行中未使用 --version=<pkgversion> 定义

version 可以在命令行中动态定义，也可以在 recipe 中使用 set_version() 方法 以编程方式定义。

user

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

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

channel

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

channel 可以在命令行中使用 --channel=<mychannel> 指定

元数据

可选元数据，例如许可证、描述、作者等。对于大多数情况不是必需的，但可能很有用。

description

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

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"""

license

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

这将帮助希望自动化许可证兼容性检查的人员，例如您的包的消费者，或者如果您的包具有开源依赖项，则可以帮助您。

class Pkg(ConanFile):
    license = "MIT"

author

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

class HelloConan(ConanFile):
    author = "John J. Smith ([email protected])"

topics

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

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

homepage

正在打包的库的主页。

用于将 recipe 链接到库本身的进一步说明，例如其功能概述、文档、FAQ 以及其他相关信息。

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

如果预发布版本已激活，例如定义配置 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

另请参阅

tool_requires

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

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 中不鼓励使用，并且将在未来的 2.X 版本中弃用。请在您的 Conan 2 recipe 中使用 tool_requires 而不是 build_requires。

test_requires

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

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

这是添加 test_requires 的声明式方法。查看 test_requires() 方法，以了解添加它们的更灵活方法。

python_requires

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

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

此类属性定义一个或多个将在运行时注入为 recipe 类基类的类。这些类中每一个的语法都应为字符串，如 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

字符串列表或元组，包含 文件名 或 fnmatch 模式，这些模式应导出并与 conanfile.py 文件并排存储，以使 recipe 工作：recipe 将导入的其他 python 文件，一些包含要读取的数据的文本文件，……

例如，如果我们有一些想要 recipe 在 helpers.py 文件中使用的 python 代码，并且有一些我们想要在 recipe 评估期间读取和显示的文本文件 info.txt，我们将执行类似以下操作

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

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

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

另请参阅

exports_sources

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

这是使用 source() 方法获取源代码的替代方法。当我们没有打包第三方库，并且我们将 recipe 和 C/C++ 项目放在一起时使用

exports_sources = "include*", "src*"

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

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

注意，如果 recipe 定义了 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", "."))

conan_data

只读属性，包含一个字典，其中包含 conandata.yml 文件格式中提供的键和值，该文件格式放置在 conanfile.py 旁边。此 YAML 文件会自动与 recipe 一起导出，并自动加载。

您可以在 conandata.yml 文件中声明信息，然后在 recipe 的任何方法中访问它。例如，包含有关源信息的 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

二进制模型

定义包二进制模型的重要属性，其中 settings、options、包类型等会影响最终打包的二进制文件。

package_type

可选。声明 package_type 将帮助 Conan

  • 为每个依赖项更好地选择默认的 package_id_mode，即依赖项中的更改应如何影响当前包的 package_id。

  • 应将哪些来自依赖项的信息传播给消费者，例如头文件、库、运行时信息。请参阅 此处 以查看基于 package_type 信息传播哪些特征。

有效值是

  • application：包是一个应用程序。

  • library：包是一个通用库。它将尝试通过读取 self.options.shared（如果已声明）和 self.options.header_only 来确定库的类型（从 shared-library、static-library、header-library）

  • shared-library：包是一个共享库。

  • static-library：包是一个静态库。

  • header-library：包是一个仅包含头文件的库。

  • build-scripts：包仅包含构建脚本。

  • python-require：包是一个 python require。

  • unknown：包的类型未知。

settings

字符串列表，包含 recipe 需要的第一级设置（来自 settings.yml），因为： - 它们被读取用于构建（例如：if self.settings.compiler == “gcc”） - 它们影响 package_id。如果声明的设置值发生更改，则 package_id 必须不同。

最常见的是声明

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

一旦 recipe 被 Conan 加载，settings 将被处理，并且可以在 recipe 中读取它们，以及子设置

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.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

字典，包含仅影响当前 recipe 的特征，其中键是选项名称，值是选项可以采用的不同值的列表。默认情况下，选项中的任何值更改都会更改 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"],
}

一旦 recipe 被 Conan 加载，options 将被处理，并且可以在 recipe 中读取它们。您还可以使用方法 .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"，以及在 Python 代码中以相同方式评估的任何其他值，等于 True。

  • 对于值 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")

另请参阅

  • 阅读 入门，创建包 以了解如何声明以及如何为选项定义值。

  • 在 package_id() 方法中删除选项。 <MISSING PAGE>

  • 关于 package_type 以及当声明 shared 选项时它如何发挥作用。 <MISSING PAGE>

default_options

属性 default_options 定义选项的默认值，包括当前 recipe 和任何需求。此属性应定义为 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 或任何带有 * 的模式，如上面的示例。

警告

在 recipe 中定义选项值没有强保证，请检查 有关依赖项选项值的常见问题解答。定义选项值的推荐方法是在 profile 文件中。

您还可以使用 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() 方法中分配了值，则无法覆盖它。

另请参阅

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

  • 当前 recipe 的任何其他下游用户，如果为 mypkg 定义了相同的选项，都将具有优先权，覆盖当前 recipe 的 123 值。profile 或命令行中的任何定义也将具有优先权。recipe default_options 的优先级最低。如果 recipe 在某些依赖项选项下根本无法工作，则 recipe 可以检查并相应地引发 ConanInvalidConfiguration 错误。

  • 任何依赖于 mypkg 的同级包也将定义其选项，并且这将是唯一被考虑的选项。换句话说，任何其他包第一次需要 mypkg 时，都会“冻结”其当前分配的选项值。任何稍后依赖于 mypkg 的包，关闭依赖关系图中的菱形结构，都不会对 mypkg 选项产生任何影响。只有第一个需要它的包才会产生影响。

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

警告

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

recipe 可以使用语法 default_options = {"mypkg/*:myoption!", 123} 将其依赖项选项定义为 important!。这意味着 mypkg myoption 不会被其他下游包、profile 或命令行覆盖，这些下游包、profile 或命令行对选项进行常规定义（如 -o *:myoption=234）。

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

  • 如果任何下游 recipe、命令行或 profile 也使用 myoption! 语法，则它也将具有优先权并覆盖上游值

  • 如果任何其他包首先需要 mypkg，则在该时刻定义的值仍将具有优先权。

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

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 属性是一个可选属性，可以字典的形式定义。字典的键是选项名称，值是以文本格式描述选项。此属性用于提供关于每个选项的功能和用途的额外信息，特别是当选项不是不言自明或具有复杂或特殊行为时。

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

  • 键（Key）：选项名称。必须是字符串，并且必须与 options 字典中的键之一匹配。

  • 值（Value）：选项的描述。必须是字符串，长度可以根据需要而定。

例如：

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 recipe 属性 languages 来定义此软件包中涉及的编程语言。目前，C 和 C++ 语言是可能的值。例如，一个纯 C 软件包将定义为：

class ZLib(ConanFile):
    languages = "C"

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

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

  • 如果未定义 languages 或 C 不是声明的语言，则 compiler.cstd 子设置将在软件包 configure() 时自动删除（以实现向后兼容性）。

  • 如果定义了 languages，但不包含 C++，则 compiler.cppstd 和 compiler.libcxx 子设置将在软件包 configure() 时自动删除。

info

专门在 package_id() 方法中使用的对象

  • :ref:package_id 方法<reference_conanfile_methods_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

package_id_embed_mode, package_id_non_embed_mode, package_id_python_mode, package_id_unknown_mode 是可以在 recipes 中定义的类属性，用于定义它们对其消费者 package_id 的影响。可以声明为：

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"

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

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

  • patch_mode：软件包的新补丁、次要版本和主要版本将需要消费者的新二进制文件（新的 package_id）。新的 recipe 修订版本将不需要消费者的新二进制文件。例如，如果我们创建一个新的 pkg/1.0.1 版本，并且某些消费者具有 requires = "pkg/[>=1.0 <2.0]"，则此类消费者将针对此特定的新 1.0.1 版本构建新的二进制文件。但是，如果我们仅更改 recipe，生成新的 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：在消费者的 package_id 中使用 pkgname/version@user/channel#recipe_revision，即除了依赖项的 package_id 之外的完整引用。

4 个不同的属性是：

  • package_id_embed_mode：定义 “embedding” 情况的模式，即，链接静态库的共享库、链接静态库的应用程序、链接仅包含头文件的库的应用程序或库。此模式的默认值为 full_mode

  • package_id_non_embed_mode。定义 “non-embedding” 情况的模式，即，链接另一个共享库的共享库、链接另一个静态库的静态库、链接共享库的应用程序可执行文件。此模式的默认值为 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。提供此属性是为了完整性和特殊情况，例如临时迁移。

另请参阅

阅读 二进制模型参考 以全面了解 Conan 二进制模型。

Build

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

Folders and layout

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 值连接而构建的。

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

recipe conanfile.py 存储的文件夹，无论是在本地文件夹还是在缓存中。 这对于访问与 recipe 一起导出的文件，或者在 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() 方法中使用，以保存或复制 recipe 元数据文件。 有关更多信息，请参阅 元数据部分。

package_metadata_folder

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

no_copy_source

no_copy_source 属性告诉 recipe，源代码不会从 source_folder 复制到 build_folder。 这主要是针对具有大型代码库或仅包含头文件的软件包的优化，以避免额外的复制。

如果您激活 no_copy_source=True，则必须确保 configure 或 build 脚本完全不修改源代码，因为源代码将在所有构建之间共享。

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

另请参阅

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

test_package_folder

test_package_folder 类属性允许在 recipe 中为 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 的位置。

Layout

folders

folders 属性必须仅在 layout() 方法中设置。 请查看 layout() 方法文档，以了解有关此属性的更多信息。

cpp

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

  • self.cpp.package：对于从 Conan 缓存中使用的常规软件包。与在 package_info() 方法中声明 self.cpp_info 相同。

  • self.cpp.source：对于 “editable” 软件包，用于描述 self.source_folder 下的工件。

  • self.cpp.build：对于 “editable” 软件包，用于描述 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 recipe，并且我们希望以 “editable” 模式拥有该 recipe，那么在创建的软件包之前，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"))

Package information for consumers

cpp_info

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

另请参阅

重要提示

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

buildenv_info

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

重要提示

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

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

另请参阅

查看 Environment 对象的参考，以了解如何填充 self.buildenv_info。

runenv_info

对于依赖 recipe，声明的环境变量将在运行时存在。 应仅在 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

要传递给依赖 recipe 的配置变量。 应仅在 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 稳定性 部分。

要传递给依赖 recipe 的生成器。 应仅在 package_info() 方法中填充。

另请参阅

请参阅 此处的示例用法 和 self.generator_info 的完整参考。

deprecated

此属性声明 recipe 已弃用，导致在使用它时发出用户友好的警告消息。

例如，以下代码：

from conan import ConanFile

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

可能会发出类似以下的警告：

cpp-taskflow/1.0: WARN: Recipe 'cpp-taskflow/1.0' is deprecated. Please, consider changing your requirements.

或者，该属性可以指定建议的替换名称：

from conan import ConanFile

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

这将发出类似以下的警告：

cpp-taskflow/1.0: WARN: Recipe 'cpp-taskflow/1.0' is deprecated in favor of 'taskflow'. Please, consider changing your requirements.

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

provides

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

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

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

属性值应为字符串，其中包含 recipe 名称或此类 recipe 名称的元组。

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

from conan import ConanFile

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

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

from conan import ConanFile

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

如果省略该属性，则假定该属性的值等于当前软件包名称。 因此，libjpeg recipe 声明它提供 libjpeg 是多余的，Conan 已经隐式假定了这一点。

Other

dependencies

Conan recipes 通过 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 的完整参考。

subgraph

（实验性）recipe 的只读依赖关系图。 dependencies 属性应用于访问 recipe 的依赖项，因为此属性旨在传递给其他 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 属性是一个只读属性。 它只能在配置文件和命令行中定义，但绝不能由 recipes 设置。 Recipes 只能通过 self.conf.get() 方法读取其值。

Output

Output contents

使用 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

此属性允许每个 recipe 声明应如何计算 recipe 本身的修订版本。 它可以采用三个不同的值：

  • "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，它定义了可以加载和理解当前 conanfile.py 的有效 Conan 版本范围。语法如下

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 版本中不起作用

alias

警告

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

在 Conan 2 中，alias 属性仍然是配方的一部分，允许用户为软件包版本定义别名。通常，您可以使用带有 alias 模板的 conan new 命令创建别名，并使用 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}