扩展二进制模型¶
有几种机制可以扩展默认的 Conan 二进制模型
自定义设置¶
可以在 settings.yml 文件中添加新的设置或子设置,例如
os:
Windows:
new_subsetting: [null, "subvalue1", "subvalue2"]
new_root_setting: [null, "value1", "value2"]
其中 null
值允许在配置文件中将设置保留为未定义状态。如果不包含此值,则配置文件必须为其定义一个值。
自定义设置将在 recipe 和包中显式或隐式使用
class Pkg(ConanFile):
# If we explicilty want this package binaries to vary according to 'new_root_setting'
settings = "os", "compiler", "build_type", "arch", "new_root_setting"
# While all packages with 'os=Windows' will implicitly vary according to 'new_subsetting'
另请参阅
有关如何自定义 settings.yml
文件的完整参考,请访问设置部分。实际上,没有必要修改 settings.yml
文件,相反,可以提供 settings_user.yml
文件来扩展现有设置。请参阅settings_user.yml 文档。
自定义选项¶
Options
对每个 recipe 都是自定义的,不像 settings.yml
那样有全局选项定义。
包的 conanfile.py
recipe 定义了自己的选项,包括其有效的取值范围和默认值
class MyPkg(ConanFile):
...
options = {"build_tests": [True, False],
"option2": ["ANY"]}
default_options = {"build_tests": True,
"option1": 42,
"z*:shared": True}
选项 shared
、fPIC
和 header_only
对 Conan 具有特殊含义,并被大多数内置构建系统集成自动考虑。它们也是表示库是共享、静态还是仅头文件时推荐的默认值。
Settings、options 与 conf 对比¶
何时使用 settings、options 或 configuration?
Settings 是项目范围的配置,通常影响正在构建的整个项目并影响生成的包二进制文件。例如,操作系统或架构对于依赖图中的所有包自然是相同的,将 Linux 库链接到构建 Windows 应用程序,或混合架构是不可能的。Settings 不能在包 recipe 中设置默认值。给定库的 recipe 不能说其默认值是
os=Windows
。os
将由处理该 recipe 的环境提供。它是必须在输入配置文件中定义的强制输入。另一方面,options 是包特有的配置,会影响生成的包二进制文件。静态库或共享库不是适用于所有包的 settings。有些可以是仅头文件库,而其他包可能只是数据或包可执行文件。例如,
shared
是一个常用选项(用于指定库是静态还是共享的默认值),但包可以定义和使用它们想要的任何选项。Options 在包的conanfile.py
recipe 中定义,包括其支持的值和默认值,通过options
和default_options
进行设置。通过
conf
进行的配置通常不影响生成的包二进制文件。例如,使用tools.cmake.cmaketoolchain:generator=Ninja
构建一个库,不应导致与使用 Visual Studio 构建的二进制文件不同(通常只是因为 Ninja 构建速度更快)。
上述情况也有一些例外。例如,可以在配置文件和命令行中,使用 <pattern:>setting=value
为每个包定义设置
$ conan install . -s mypkg/*:compiler=gcc -s compiler=clang ..
这将对 “mypkg” 使用 gcc
,对其余依赖项使用 clang
(在大多数情况下,建议对整个依赖图使用相同的编译器,但在某些保证强大二进制兼容性的情况下,可以混合使用不同编译器构建的库)。
在某些情况下,许多包使用相同的选项值,因此可以使用模式一次性设置其值,例如
$ conan install . -o *:shared=True
自定义配置¶
如上所述,Conan 的 conf
配置系统旨在调整某些工具和行为,但不会真正影响生成的包二进制文件。一些典型的 conf
项包括激活并行构建、配置上传到服务器时的“重试”次数,或更改 CMake 生成器。有关 Conan 配置系统的更多信息,请参阅此部分。
还可以为用户自定义配置定义 user.xxxx:conf=value
,其与核心和工具的内置配置精神相同,不影响二进制文件的 package_id
。
但是,在某些特殊情况下,确实希望某些 conf
定义不同的 package_ids
,从而创建不同的包二进制文件。可以通过两种不同的方式实现这一点
在本地,通过 recipe 的
package_id
方法,使用self.info.conf
属性def package_id(self): # We can get the value from the actual current conf value, or define a new value value = self.conf.get("user.myconf:myitem") # This ``self.info.conf`` will become part of the ``package_id`` self.info.conf.define("user.myconf:myitem", value)
全局地,通过
tools.info.package_id:confs
配置,接收一个现有配置列表作为参数,该列表将成为包 ID 的一部分,因此可以在配置文件中定义tools.info.package_id:confs=["tools.build:cxxflags", ...]
package_id
的值将包含在tools.build:cxxflags
和其他配置中提供的值。请注意,此值作为字符串管理,更改字符串将产生不同的结果和不同的package_id
,因此如果使用此方法,对不同配置(如tools.build:cxxflags
)提供的值保持高度一致性非常重要。也可以使用正则表达式来匹配多个
confs
,而不是列出所有confs
,例如.*cmake
可以匹配名称中包含“cmake”的任何配置(不推荐这样做,请参阅下面的最佳实践)。
注意
最佳实践
一般来说,通过 conf
定义二进制 package_id
的可变性应保留用于特殊情况,并始终谨慎管理。将许多不同的 confs
传递给 tools.info.package_id:confs
很容易导致二进制文件缺失或不必要地构建过多二进制文件等问题。如果出现这种情况,请考虑使用新的自定义设置或选项在二进制文件之上构建更高级别的抽象。
交叉构建目标设置¶
self.settings_target
是一个 conanfile.py
属性,在交叉编译场景中对“构建”上下文中的 tool_requires
工具变得相关。当我们有一个 tool_requires
,比如 CMake,假设是 cmake/3.25.3
,那么包二进制文件与交叉编译可能面向的平台无关,对于所有不同的目标平台,它都是相同的 cmake
可执行文件。对于 cmake
conanfile recipe,从 Windows-X64 交叉构建到 Linux-armv8 场景的 settings
将是
self.settings
:当前cmake/3.25.3
将运行的设置。由于它是一个 tool-require,它将在 Windows 机器上运行,因此self.settings.os = Windows
和self.settings.arch = x86_64
。self.settings_build
:如果需要构建此包,当前构建机器的设置。这也是 Windows-x64 机器,因此self.settings_build.os = Windows
和self.settings_build.arch = x86_64
。self.settings_target
:当前应用程序结果将面向的设置。在这种情况下,它将是self.settings_target.os = Linux
和self.settings_target.arch = armv8
在 cmake
包的场景中,正如我们指出的,目标是无关紧要的。它根本没有在 cmake
conanfile recipe 中使用,并且不影响 cmake
二进制包的 package_id
。
但是,在某些情况下,二进制包可能会因目标平台而异。例如,一个交叉编译器 gcc
,其 gcc
可执行文件会根据其编译的目标而有所不同。这在 GNU 生态系统中很常见,例如我们可以找到 arm-gcc
工具链,它们是针对特定架构的。Conan 可以反映这种场景,通过 settings_target
的值来扩展 package_id
def package_id(self):
self.info.settings_target = self.settings_target
# If we only want the ``os`` and ``arch`` settings, then we remove the other:
self.info.settings_target.rm_safe("compiler")
self.info.settings_target.rm_safe("build_type")