配置文件¶
配置文件简介¶
Conan 配置文件允许用户在文件中设置一套完整的配置,包括**设置**、**选项**、**环境变量**(用于构建时和运行时上下文)、**工具要求**和**配置变量**。
它们的结构如下:
[settings]
arch=x86_64
build_type=Release
os=Macos
[options]
mylib/*:shared=True
[tool_requires]
tool1/0.1@user/channel
*: tool4/0.1@user/channel
[buildenv]
VAR1=value
[runenv]
EnvironmentVar1=My Value
[conf]
tools.build:jobs=2
[replace_requires]
zlib/1.2.12: zlib/[*]
[replace_tool_requires]
7zip/*: 7zip/system
[platform_requires]
dlib/1.3.22
[platform_tool_requires]
cmake/3.24.2
配置文件可以通过 conan profile 命令中的 detect
选项创建,然后进行编辑。如果您不指定**名称**,该命令将创建 default
配置文件。
$ conan profile detect
apple-clang>=13, using the major as version
Detected profile:
[settings]
arch=x86_64
build_type=Release
compiler=apple-clang
compiler.cppstd=gnu17
compiler.libcxx=libc++
compiler.version=14
os=Macos
WARN: This profile is a guess of your environment, please check it.
WARN: Defaulted to cppstd='gnu17' for apple-clang.
WARN: The output of this command is not guaranteed to be stable and can change in future Conan versions.
WARN: Use your own profile files for stability.
Saving detected profile to [CONAN_HOME]/profiles/default
注意
关于 Conan 检测到的 C++ 标准的说明
Conan 总是将默认 C++ 标准设置为所检测到的编译器版本默认使用的标准,macOS 使用 apple-clang 的情况除外。在这种情况下,对于 apple-clang >= 11,它将 compiler.cppstd=gnu17
。如果您想使用不同的 C++ 标准,可以直接编辑默认配置文件。
$ conan profile detect --name myprofile
Found apple-clang 14.0
apple-clang>=13, using the major as version
Detected profile:
[settings]
arch=x86_64
build_type=Release
compiler=apple-clang
compiler.cppstd=gnu17
compiler.libcxx=libc++
compiler.version=14
os=Macos
WARN: This profile is a guess of your environment, please check it.
WARN: Defaulted to cppstd='gnu17' for apple-clang.
WARN: The output of this command is not guaranteed to be stable and can change in future Conan versions.
WARN: Use your own profile files for stability.
Saving detected profile to [CONAN_HOME]/profiles/myprofile
配置文件可以在许多命令中使用 -pr
/--profile
选项,例如 conan install 或 conan create 命令。如果您根本没有指定任何配置文件,则始终使用 default
配置文件。
$ conan create .
$ conan create . -pr=myprofile
使用配置文件¶
配置文件可以位于不同的文件夹中
$ conan install . -pr /abs/path/to/myprofile # abs path
$ conan install . -pr ./relpath/to/myprofile # resolved to current dir
$ conan install . -pr ../relpath/to/myprofile # resolved to relative dir
$ conan install . -pr myprofile # resolved to [CONAN_HOME]/profiles/myprofile
列出 *profiles* 文件夹中现有的配置文件可以这样做:
$ conan profile list
Profiles found in the cache:
default
myprofile1
myprofile2
...
您还可以按上下文显示配置文件的内容
$ conan profile show -pr myprofile
Host profile:
[settings]
arch=x86_64
build_type=Release
compiler=apple-clang
compiler.cppstd=gnu17
compiler.libcxx=libc++
compiler.version=14
os=Macos
Build profile:
[settings]
arch=x86_64
build_type=Release
compiler=apple-clang
compiler.cppstd=gnu17
compiler.libcxx=libc++
compiler.version=14
os=Macos
另请参阅
使用 conan config install 管理和共享您的配置文件。
查看 conan profile 命令及其子命令。
配置文件部分¶
以下是配置文件中可用的部分
[settings]¶
来自 settings.yml 的可用设置列表
[settings]
arch=x86_64
build_type=Release
compiler=apple-clang
compiler.cppstd=gnu17
compiler.libcxx=libc++
compiler.version=14
os=Macos
另请参阅
本节允许使用模式来限制受此设置影响的包。有关更多详细信息,请参阅 本节。
[options]¶
您的配方及其依赖项中可用的选项列表
[options]
mypkg/*:my_pkg_option=True
*:shared=True
另请参阅
本节允许使用模式来限制受这些选项影响的包。有关更多详细信息,请参阅 本节。
[tool_requires]¶
您的配方或其依赖项所需的 tool_requires
列表
[tool_requires]
cmake/3.25.2
另请参阅
本节允许使用模式来限制受工具要求影响的包。有关更多详细信息,请参阅 本节。
在此部分阅读有关工具要求的更多信息:将构建工具用作 Conan 包。
[system_tools] (已弃用)¶
注意
本节**已弃用**,已替换为 [platform_requires] 和 [platform_tool_requires] 部分。
[buildenv]¶
每次调用 ConanFile run(cmd, env="conanbuild")
方法时(构建时上下文由 VirtualBuildEnv 自动运行),将注入到环境中的环境变量列表。
除此之外,它还能够对声明的每个变量应用一些额外的运算符,以便在组合配置文件甚至本地变量时使用。
+=
==append
:将值追加到现有值的末尾。=+
==prepend
:将值放到现有值的开头。=!
==unset
:删除任何变量值。
另一个需要提及的要点是,可以通过简单地将 (path)
作为变量的前缀来定义 PATH 变量。这对于在不同系统(Windows 使用 ;
作为分隔符,UNIX 使用 :
)中自动获取 PATH 的追加/前置非常有用。
[buildenv]
# Define a variable "MyVar1"
MyVar1=My Value; other
# Append another value to "MyVar1"
MyVar1+=MyValue12
# Define a PATH variable "MyPath1"
MyPath1=(path)/some/path11
# Prepend another PATH to "MyPath1"
MyPath1=+(path)/other path/path12
# Unset the variable "MyPath1"
MyPath1=!
然后,应用此配置文件的结果是
MyVar1
:My Value; other MyValue12
MyPath1
:Unix:
/other path/path12:/some/path11
Windows:
/other path/path12;/some/path11
mypkg*:PATH
:None
警告
请注意,[buildenv]
和 [runenv]
环境变量定义保留了值中的用户空格。MYVAR = MyValue
将产生 " MyValue"
值,这与 MYVAR=MyValue
产生的 "MyValue"
不同。避免在配置文件中 =
周围使用多余的空格,请使用上面显示的语法。
另请参阅
本节允许使用模式来限制受 buildenv 影响的包。有关更多详细信息,请参阅 本节。
[runenv]¶
每次调用 ConanFile run(cmd, env="conanrun")
方法时(运行时上下文由 VirtualRunEnv 自动运行),将注入到环境中的环境变量列表。
为 [buildenv] 解释的所有运算符/模式以相同的方式适用于此项。
[runenv]
MyVar1=My Value; other
MyVar1+=MyValue12
MyPath1=(path)/some/path11
MyPath1=+(path)/other path/path12
MyPath1=!
另请参阅
本节允许使用模式来限制受 runenv 影响的包。有关更多详细信息,请参阅 本节。
[conf]¶
注意
建议您先阅读 global.conf 部分。
用户/工具配置列表
[conf]
tools.build:verbosity=verbose
tools.microsoft.msbuild:max_cpu_count=2
tools.microsoft.msbuild:vs_version = 16
tools.build:jobs=10
# User conf variable
user.confvar:something=False
回顾一些关于配置范围和命名点的提示
core.xxx
配置只能在global.conf
文件中定义,不能在配置文件中定义。tools.yyy
和user.zzz
可以在global.conf
中定义,并且会影响“构建”和“主机”上下文。但在配置文件[conf]
中定义的配置只会影响配置文件的相应“构建”或“主机”上下文,而不是两者都影响。
它们也可以在 global.conf 中使用,但是 **配置文件值将优先于 global.conf 中全局定义的值**,因此让我们看一个更复杂的示例,尝试来自 *global.conf* 和另一个配置文件 *myprofile* 的不同配置
# Defining several lists
user.myconf.build:ldflags=["--flag1 value1"]
user.myconf.build:cflags=["--flag1 value1"]
[settings]
...
[conf]
# Appending values into the existing list
user.myconf.build:ldflags+=["--flag2 value2"]
# Unsetting the existing value (it'd be like we define it as an empty value)
user.myconf.build:cflags=!
# Prepending values into the existing list
user.myconf.build:ldflags=+["--prefix prefix-value"]
例如,运行 conan install . -pr myprofile,配置输出将如下所示
...
Configuration:
[settings]
[options]
[tool_requires]
[conf]
user.myconf.build:cflags=!
user.myconf.build:ldflags=['--prefix prefix-value', '--flag1 value1', '--flag2 value2']
...
另请参阅
本节允许使用模式来限制受 confs 影响的包。有关更多详细信息,请参阅 本节。
[replace_requires]¶
警告
此功能是实验性的,可能会发生重大更改。有关更多信息,请参阅 Conan 稳定性 部分。
本节允许用户重新定义配方的依赖项。当一个包可以被一个类似的包(例如 zlib 和 zlibng)替换时,这可能很有用。它对于解决冲突或用封装在另一个 Conan 包配方中的系统替代方案替换某些依赖项也很有用。
此部分下列出的引用作为**配方中依赖项的文字替换**,并在对配方要求进行任何其他处理之前作为第一步完成,不处理它们也不检查冲突。
例如,我们可以将 zlibng 定义为典型 zlib 的替代品
[replace_requires]
zlib/*: zlibng/*
对 zlibng
引用使用 *
模式意味着 zlib
将被 zlibng
的完全相同的版本替换。
其他例子是
[replace_requires]
dep/*: dep/1.1 # To override dep/[>=1.0 <2] in recipes to a specific version dep/1.1)
dep/*: dep/*@system # To override a dep/1.3 in recipes to dep/1.3@system
dep/*: dep/[>=1 <2] # To override every dep requirement in recipes to a specific version range
dep/*@*/*: dep/*@system/* # To override "dep/1.3@comp/stable" in recipes to the same version with other user but same channel
dep/1.1: dep/1.1@system # To replace exact reference in recipes by the same one in the system
dep/1.1@*: dep/1.1@*/stable # To replace dep/[>=1.0 <2]@comp version range in recipes by 1.1 version in stable chanel
注意
最佳实践
请合理使用此功能。它不是版本控制机制,也不是为了取代配方中的实际要求。
此功能旨在**暂时**解决冲突,或在某些交叉构建场景中用系统依赖项替换特定依赖项。
[replace_tool_requires]¶
警告
此功能是实验性的,可能会发生重大更改。有关更多信息,请参阅 Conan 稳定性 部分。
与 replace_requires 部分用法相同,但在此情况下用于 tool_requires。
[replace_tool_requires]
cmake/*: cmake/3.25.2
在这种情况下,配方中声明的任何版本的 cmake
都将被引用 cmake/3.25.2 替换。
注意
本节应添加到其上下文需要该工具的配置文件中,即,如果该工具在主机上下文中被需要,则应将其添加到主机配置文件中,以便可以替换该要求本身。
[platform_requires]¶
警告
此功能是实验性的,可能会发生重大更改。有关更多信息,请参阅 Conan 稳定性 部分。
本节允许用户重新定义配方的依赖项,将其替换为平台提供的依赖项,这意味着 Conan 不会尝试下载引用或在缓存中查找它,并会假定它已安装在您的系统中并可以使用。
例如,如果 zlib 1.2.11 库已安装在您的系统中或它是您的构建工具链的一部分,并且您希望 Conan 使用它,您可以这样指定:
[platform_requires]
zlib/1.3.1
[platform_tool_requires]¶
警告
此功能是实验性的,可能会发生重大更改。有关更多信息,请参阅 Conan 稳定性 部分。
用法与 platform_requires 部分相同,但此处用于 tool_requires,例如 cmake、meson… 等。
例如,假设您已在系统上安装了 cmake==3.24.2
$ cmake --version
cmake version 3.24.2
CMake suite maintained and supported by Kitware (kitware.com/cmake).
并且您的配方中(或传递依赖项中)声明了 **tool_requires**,即,像这样:
from conan import ConanFile
class PkgConan(ConanFile):
name = "pkg"
version = "2.0"
# ....
# Exact version
def build_requirements(self):
self.tool_requires("cmake/3.24.2")
# Or even version ranges
def build_requirements(self):
self.tool_requires("cmake/[>=3.20.0]")
在这种情况下,您可能希望使用已安装的 CMake 版本,因此只需在您的配置文件中将其声明为 platform_tool_requires
即可
...
[platform_tool_requires]
cmake/3.24.2
每当您想创建包时,您会看到由于平台工具声明,构建要求已满足
$ conan create . -pr myprofile --build=missing
...
-------- Computing dependency graph --------
Graph root
virtual
Requirements
pkg/2.0#3488ec5c2829b44387152a6c4b013767 - Cache
Build requirements
cmake/3.24.2 - Platform
-------- Computing necessary packages --------
-------- Computing necessary packages --------
pkg/2.0: Forced build from source
Requirements
pkg/2.0#3488ec5c2829b44387152a6c4b013767:20496b332552131b67fb99bf425f95f64d0d0818 - Build
Build requirements
cmake/3.24.2 - Platform
注意
如果声明的
platform_tool_requires
**与**tool_requires
**不严格匹配**(版本或版本范围),那么 Conan 将像往常一样尝试远程或本地获取它们。本节应添加到其上下文需要该工具的配置文件中,即,如果该工具在主机上下文中被需要,则应将其添加到主机配置文件中,以便可以将其要求替换为平台要求。
配置文件渲染¶
配置文件默认渲染为 **jinja2** 模板。当 Conan 加载配置文件时,它会立即解析并渲染模板,结果必须是一个标准文本配置文件。
配置文件模板的一些功能是
使用平台信息(例如获取当前操作系统)是可能的,因为 Python
platform
模块已添加到渲染上下文。profile_vars¶[settings] os = {{ {"Darwin": "Macos"}.get(platform.system(), platform.system()) }}
可以读取环境变量,因为 Python
os
模块已添加到渲染上下文。profile_vars¶[settings] build_type = {{ os.getenv("MY_BUILD_TYPE") }}
定义自己的变量并在配置文件中使用它们
profile_vars¶{% set os = "FreeBSD" %} {% set clang = "my/path/to/clang" %} [settings] os = {{ os }} [conf] tools.build:compiler_executables={'c': '{{ clang }}', 'cpp': '{{ clang + '++' }}' }
连接和定义路径,包括引用当前配置文件目录。例如,可以定义一个工具链,其文件位于配置文件旁边。除了
os
Python 模块之外,指向当前配置文件文件夹的变量profile_dir
也已添加到上下文中。profile_vars¶[conf] tools.cmake.cmaketoolchain:toolchain_file = {{ os.path.join(profile_dir, "toolchain.cmake") }}
从文件名获取设置,包括引用当前配置文件名。例如,定义一个通用配置文件,该配置文件根据其文件名进行配置。指向当前配置文件文件名的变量
profile_name
已添加到上下文中。Linux-x86_64-gcc-12¶{% set os, arch, compiler, compiler_version = profile_name.split('-') %} [settings] os={{ os }} arch={{ arch }} compiler={{ compiler }} compiler.version={{ compiler_version }}
执行外部命令并使用其输出。
subprocess
模块已添加到上下文中,因此您可以使用它来执行命令并捕获其输出。请注意,如果命令执行时间过长,某些命令的 Conan 启动时间可能会受到影响,因此请谨慎使用此功能。例如,获取已安装编译器的版本(但在这种情况下,您应该改用detect_api.detect_default_compiler()
)。profile_vars¶{% set version = subprocess.check_output(['clang++', "-dumpversion]).strip() %} [settings] compiler.version={{ version }}
根据配置文件正在渲染的上下文进行分支。变量
context
被注入,并且可以取值host
、build
或为None
。例如,您可以为 host 和 build 上下文定义不同的设置,而无需创建两个不同的配置文件。profile_vars¶[settings] os=Linux compiler=gcc compiler.version=12 {% if context == "host" %} compiler.cppstd=gnu17 {% else %} compiler.cppstd=gnu20 {% endif %}
从
profiles
文件夹中包含或导入其他文件profile_vars¶{% set a = "Debug" %}
myprofile¶{% import "profile_vars" as vars %} [settings] build_type = {{ vars.a }}
当使用相对路径包含或导入其他文件时,Jinja 渲染器将当前配置文件文件的基本路径作为第一个查找位置。如果此查找失败,Jinja 渲染器还将开始在 Conan home profiles 文件夹(通常在
<userhome>/.conan2/profiles
中)中查找。jinja2 支持的任何其他功能都是可能的:for 循环、if-else 等。这对于在大型依赖关系图中为多个包定义自定义的按包设置或选项非常有用。
使用 ``detect_api`` 渲染配置文件
警告
**稳定性保证**:detect_api,类似于 conan profile detect
,不提供强大的稳定性保证。
**使用建议**:detect_api 不是用于创建新命令或类似功能的常规 API。虽然自动检测很方便,但它并非适用于所有场景的推荐方法。此 API 是 Conan 内部的,仅用于配置文件和 *global.conf* 渲染。建议您谨慎使用。
Conan 还将 detect_api
注入到 jinja 渲染上下文中。通过它,可以直接在 Jinja 配置文件模板中使用 Conan 的自动检测功能。这提供了一种根据环境动态确定某些设置的方法。
detect_api
可以在配置文件的 Jinja 模板中调用。例如,要检测操作系统和架构,您可以使用
[settings]
os={{detect_api.detect_os()}}
arch={{detect_api.detect_arch()}}
同样,对于更高级的检测,例如确定编译器、其版本和相关的运行时,您可以使用
{% set compiler, version, compiler_exe = detect_api.detect_default_compiler() %}
{% set runtime, _ = detect_api.default_msvc_runtime(compiler) %}
[settings]
compiler={{compiler}}
compiler.version={{detect_api.default_compiler_version(compiler, version)}}
compiler.runtime={{runtime}}
compiler.cppstd={{detect_api.default_cppstd(compiler, version)}}
compiler.libcxx={{detect_api.detect_libcxx(compiler, version, compiler_exe)}}
detect_api 参考:
detect_os()
:以字符串形式返回操作系统(例如,“Windows”,“Macos”)。
detect_arch()
:以字符串形式返回系统架构(例如,“x86_64”,“armv8”)。
detect_libc(ldd="/usr/bin/ldd")
:**实验性**,返回一个包含 C 库名称(例如,“gnu”,“musl”)和版本(例如,“2.39”,“1.2.4”)的元组。
detect_libcxx(compiler, version, compiler_exe=None)
:以字符串形式返回 C++ 标准库(例如,“libstdc++”,“libc++”)。
default_msvc_runtime(compiler)
:返回包含运行时(例如,“dynamic”)及其版本(例如,“v143”)的元组。
default_cppstd(compiler, compiler_version)
:以字符串形式返回默认 C++ 标准(例如,“gnu14”)。
detect_default_compiler()
:返回包含编译器名称(例如,“gcc”)、其版本和可执行文件路径的元组。
detect_msvc_update(version)
:返回 MSVC 更新版本作为字符串(例如,VS 17.12.1 为“12”)。请注意,在 Conan 配置文件中,compiler.update
设置接受 0 到 10 之间的值。要将detect_msvc_update
的结果转换为配置文件所需的格式,您可以执行以下操作示例
... [settings] compiler=msvc compiler=194 # for msvc toolset starting in 14.40 (VS 17.10) # If we are using VS 17.12 we convert 12 to 2 so it's 194 with update 2 compiler.update = "{{ (detect_api.detect_msvc_update(version) | int) % 10 }}" ...
default_msvc_ide_version(version)
:返回 MSVC IDE 版本字符串(例如,“17”)。
default_compiler_version(compiler, version)
:返回 Conan 在配置文件中使用的默认版本,通常会删除一些不影响二进制兼容性的次要或补丁位。
detect_gcc_compiler(compiler_exe="gcc")
:返回gcc
的元组 ('gcc', 版本, 可执行文件)。
detect_intel_compiler(compiler_exe="icx")
:返回intel-cc
的元组 ('intel-cc', 版本, 可执行文件)。
detect_suncc_compiler(compiler_exe="cc")
:返回sun-cc
的元组 ('sun-cc', 版本, 可执行文件)。
detect_clang_compiler(compiler_exe="clang")
:返回clang
或apple-clang
的元组 ('clang'|'apple-clang', 版本, 可执行文件)。
detect_msvc_compiler()
:检测编译器 ('msvc', version, None) 最新安装的 VS IDE 的默认版本
detect_cl_compiler(compiler_exe="cl")
:检测cl.exe
编译器的编译器 ('msvc', 版本, 可执行文件)。
detect_sdk_version(sdk)
:检测给定sdk
的 Apple SDK 版本(非 Apple 平台为None
)。相当于xcrun -sdk {sdk} --show-sdk-version
。
配置文件模式¶
配置文件(以及定义设置或选项的任何地方)也支持模式定义,因此您可以为某些特定包覆盖某些设置、配置变量等。
[settings]
# Only for zlib
zlib/*:compiler=clang
zlib/*:compiler.version=3.5
zlib/*:compiler.libcxx=libstdc++11
# For the all the dependency tree
compiler=gcc
compiler.version=4.9
compiler.libcxx=libstdc++11
[options]
# shared=True option only for zlib package
zlib/*:shared=True
[buildenv]
# For the all the dependency tree
*:MYVAR=my_var
[conf]
# Only for zlib
zlib/*:tools.build:compiler_executables={'c': '/usr/bin/clang', 'cpp': '/usr/bin/clang++'}
您的构建工具将只为 **zlib** 包定位 **clang** 编译器,而为依赖项树的其余部分定位 **gcc**(默认)。
重要
仅放置 zlib:
是已弃用的行为,将不起作用,您必须始终放置类似模式的表达式,例如 zlib*:
、zlib/*:
、zlib/1.*:
等。
它们也接受模式,例如 -s *@myuser/*
,这意味着具有用户名“myuser”的包将使用 clang 3.5 作为编译器,否则使用 gcc。
[settings]
*@myuser/*:compiler=clang
*@myuser/*:compiler.version=3.5
*@myuser/*:compiler.libcxx=libstdc++11
compiler=gcc
compiler.version=4.9
compiler.libcxx=libstdc++11
也可以指定 &
作为包名称。它将仅应用于使用者 conanfile(.py 或 .txt)。这是一个特殊情况,因为使用者 conanfile 可能没有声明 name
,因此无法引用它。
[settings]
&:compiler=gcc
&:compiler.version=4.9
&:compiler.libcxx=libstdc++11
还支持部分匹配,因此您可以定义一个模式,例如 zlib*
来匹配所有像 zlib 的库,因此它将匹配所有以 zlib 开头的内容,例如 zlib
、zlibng
、zlib/1.2.8@user/channel
等。
[settings]
zlib*:compiler=clang
zlib*:compiler.version=3.5
zlib*:compiler.libcxx=libstdc++11
如果模式以 !
开头,则它被视为排除模式,这意味着它将匹配除指定模式之外的所有内容。这对于前面提到的消费者 &
模式也适用。
使用排除模式时必须小心,因为如果使用不当,它们可能会导致意想不到的结果。
例如,要为除 zlib 之外的所有包定义一个 shared=True
选项,您可以使用
[options]
!zlib/*:shared=True
配置文件包含¶
您可以使用 include()
语句包含其他配置文件。路径可以是相对于当前配置文件、绝对路径,或者是本地缓存中默认配置文件位置的配置文件名。
include()
语句必须位于配置文件的顶部
[settings]
compiler=gcc
compiler.version=4.9
compiler.libcxx=libstdc++11
include(gcc_49)
[settings]
zlib/*:compiler=clang
zlib/*:compiler.version=3.5
zlib/*:compiler.libcxx=libstdc++11
注意
缓存配置文件比当前工作目录中的配置文件具有更高的优先级,因此如果缓存中有一个名为 myprofile
的配置文件,它将取代当前工作目录中的配置文件。
要使用当前工作目录中的配置文件,您可以使用
命令行中的
-pr ./myprofile
选项或配置文件本身中的
include(./myprofile)
。
使用 *myprofile* 的最终结果是
[settings]
compiler=gcc
compiler.libcxx=libstdc++11
compiler.version=4.9
zlib/*:compiler=clang
zlib/*:compiler.libcxx=libstdc++11
zlib/*:compiler.version=3.5
另请参阅