配置文件

配置文件简介

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 默认配置文件
$ 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++ 标准，可以直接编辑默认配置文件。

创建另一个配置文件：myprofile
$ 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

配置文件可用于许多命令（如 conan install 或 conan create 命令）中的 -pr/--profile 选项。如果根本不指定任何配置文件，则始终使用 default 配置文件

使用default配置文件
$ conan create .
使用myprofile配置文件
$ 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

另请参阅

配置文件部分

以下是配置文件中可用的部分

[settings]

来自 settings.yml 的可用设置列表

myprofile
[settings]
arch=x86_64
build_type=Release
compiler=apple-clang
compiler.cppstd=gnu17
compiler.libcxx=libc++
compiler.version=14
os=Macos

[options]

来自您的配方及其依赖项的可用选项列表

myprofile
[options]
mypkg/*:my_pkg_option=True
*:shared=True

[tool_requires]

您的配方或其依赖项所需的 tool_requires 列表

myprofile
[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 变量。这对于在不同的系统中自动获取 PATH 的追加/前置很有用（Windows 使用 ; 作为分隔符，而 UNIX 使用 :）。

myprofile
[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"。避免在配置文件中的 = 周围使用额外的空格，使用上面显示的语法。

[runenv]

每次调用 ConanFile run(cmd, env="conanrun") 方法时（运行时上下文由 VirtualRunEnv 自动运行）都会注入到环境中的环境变量列表。

为 [buildenv] 解释的所有运算符/模式都以相同的方式应用于此运算符/模式

myprofile
[runenv]
MyVar1=My Value; other
MyVar1+=MyValue12
MyPath1=(path)/some/path11
MyPath1=+(path)/other path/path12
MyPath1=!

[conf]

注意

建议您先阅读 global.conf 部分。

用户/工具配置列表

myprofile
[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 的不同配置

global.conf
# Defining several lists
user.myconf.build:ldflags=["--flag1 value1"]
user.myconf.build:cflags=["--flag1 value1"]
myprofile
[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']
...

[replace_requires]

警告

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

此部分允许用户重新定义配方的依赖项。当一个包可以被类似的包（如 zlib 和 zlibng）替换时，这很有用。它还有助于解决冲突，或用另一个 Conan 包配方中封装的系统替代项替换某些依赖项。

在此部分下列出的引用充当**配方中依赖项的字面替换**，并且是在任何其他配方需求处理之前作为第一步完成的，无需处理它们或检查冲突。

例如，我们可以将 zlibng 定义为典型 zlib 的替代项

myprofile
[replace_requires]
zlib/*: zlibng/*

对 zlibng 引用使用 * 模式意味着 zlib 将被替换为与 zlibng 完全相同版本的包。

其他示例包括

myprofile
[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。

myprofile
[replace_tool_requires]
cmake/*: cmake/3.25.2

在这种情况下，无论配方中声明的 cmake 版本如何，都将替换为引用 cmake/3.25.2。

[platform_requires]

警告

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

此部分允许用户重新定义配方的 requires，将其替换为平台提供的依赖项，这意味着 Conan 不会尝试下载引用或在缓存中查找它，而是假设它已安装在您的系统中并可以使用。

例如，如果 zlib 1.2.11 库已安装在您的系统中或它是构建工具链的一部分，并且您希望 Conan 使用它，您可以指定如下：

myprofile
[platform_requires]
zlib/1.2.11

[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，例如：

conanfile.py
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 即可

myprofile
...

[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 }}

  • 从 profiles 文件夹中包含或导入其他文件

    profile_vars
    {% set a = "Debug" %}
    myprofile
    {% import "profile_vars" as vars %}
[settings]
build_type = {{ vars.a }}

  • jinja2 支持的任何其他功能都是可能的：for 循环、if-else 等。这将有助于为大型依赖关系图中的多个包定义自定义的每个包设置或选项。

使用 ``detect_api`` 进行配置文件渲染

警告

稳定性保证：与 conan profile detect 类似，detect_api 不提供强大的稳定性保证。

用法建议：detect_api 不是用于创建新命令或类似功能的常规 API。虽然自动检测很方便，但它不是所有场景下的推荐方法。此 API 是 Conan 的内部 API，仅公开用于配置文件和 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 更新版本（例如，“7”）。

  • 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’，版本，None），即安装的最新 VS IDE 的默认版本

  • detect_cl_compiler(compiler_exe="cl")：检测编译器（‘msvc’，版本，可执行文件），即 cl.exe 编译器。

  • detect_sdk_version(sdk)：检测 Apple SDK 版本（对于非 Apple 平台为 None），用于给定的 sdk。等效于 xcrun -sdk {sdk} --show-sdk-version

配置文件模式

配置文件（以及定义设置或选项的任何地方）也支持模式定义，因此您可以为某些特定包覆盖某些设置、配置变量等

zlib_clang_profile
[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

myprofile
[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，因此无法引用它。

myprofile
[settings]
&:compiler=gcc
&:compiler.version=4.9
&:compiler.libcxx=libstdc++11

也支持部分匹配，因此您可以定义一个类似 zlib* 的模式来匹配所有类似 zlib 的库，因此它将匹配以 zlib 开头的所有内容，例如 zlib、zlibng、zlib/1.2.8@user/channel 等。

myprofile
[settings]
zlib*:compiler=clang
zlib*:compiler.version=3.5
zlib*:compiler.libcxx=libstdc++11

配置文件包含

您可以使用 include() 语句包含其他配置文件。路径可以相对于当前配置文件，也可以是绝对路径，或者来自本地缓存中默认配置文件位置的配置文件名称。

include() 语句必须位于配置文件的顶部

gcc_49
[settings]
compiler=gcc
compiler.version=4.9
compiler.libcxx=libstdc++11
myprofile
include(gcc_49)

[settings]
zlib/*:compiler=clang
zlib/*:compiler.version=3.5
zlib/*:compiler.libcxx=libstdc++11

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

另请参阅