global.conf

global.conf 文件位于 Conan 用户主目录，例如 [CONAN_HOME]/global.conf。如果它不存在，则会自动创建一个默认文件。

配置简介

global.conf 用于保存一些核心/工具/用户配置变量，Conan 将使用它们。例如：

  • 包 ID 模式。

  • 通用 HTTP (python-requests) 配置。

  • 下载/上传 recipe 时的重试次数。

  • 相关工具配置 (由 toolchains、helpers 等使用)

  • 其他 (必需的 Conan 版本、CLI 非交互式等)

简要解释三种现有的配置类型：

  • core.*: 用于配置 Conan 核心行为的值 (下载重试、包 ID 模式等)。只能在 global.conf 文件中定义。

  • tools.*: 用于配置您的 recipes 中使用的 Conan 工具 (toolchains、build helpers 等) 的值。可以在 global.conf 和 profiles 中定义。

  • user.*: 用于定义个人的用户配置。它们可以定义用户想要的任何内容。可以在 global.conf 和 profiles 中定义。

要列出所有可用的配置，请运行 conan config list

$ conan config list
core.cache:storage_path: Absolute path where the packages and database are stored
core.download:download_cache: Define path to a file download cache
core.download:parallel: Number of concurrent threads to download packages
core.download:retry: Number of retries in case of failure when downloading from Conan server
core.download:retry_wait: Seconds to wait between download attempts from Conan server
core.gzip:compresslevel: The Gzip compression level for Conan artifacts (default=9)
core.net.http:cacert_path: Path containing a custom Cacert file
core.net.http:clean_system_proxy: If defined, the proxies system env-vars will be discarded
core.net.http:client_cert: Path or tuple of files containing a client cert (and key)
core.net.http:max_retries: Maximum number of connection retries (requests library)
core.net.http:no_proxy_match: List of urls to skip from proxies configuration
core.net.http:proxies: Dictionary containing the proxy configuration
core.net.http:timeout: Number of seconds without response to timeout (requests library)
core.package_id:config_mode: How the 'config_version' affects binaries. By default 'None'
core.package_id:default_build_mode: By default, 'None'
core.package_id:default_embed_mode: By default, 'full_mode'
core.package_id:default_non_embed_mode: By default, 'minor_mode'
core.package_id:default_python_mode: By default, 'minor_mode'
core.package_id:default_unknown_mode: By default, 'semver_mode'
core.scm:excluded: List of excluded patterns for builtin git dirty checks
core.scm:local_url: By default allows to store local folders as remote url, but not upload them. Use 'allow' for allowing upload and 'block' to completely forbid it
core.sources.patch:extra_path: Extra path to search for patch files for conan create
core.sources:download_cache: Folder to store the sources backup
core.sources:download_urls: List of URLs to download backup sources from
core.sources:exclude_urls: URLs which will not be backed up
core.sources:upload_url: Remote URL to upload backup sources to
core.upload:parallel: Number of concurrent threads to upload packages
core.upload:retry: Number of retries in case of failure when uploading to Conan server
core.upload:retry_wait: Seconds to wait between upload attempts to Conan server
core.version_ranges:resolve_prereleases: Whether version ranges can resolve to pre-releases or not
core:allow_uppercase_pkg_names: Temporarily (will be removed in 2.X) allow uppercase names
core:default_build_profile: Defines the default build profile ('default' by default)
core:default_profile: Defines the default host profile ('default' by default)
core:non_interactive: Disable interactive user input, raises error if input necessary
core:required_conan_version: Raise if current version does not match the defined range.
core:skip_warnings: Do not show warnings matching any of the patterns in this list. Current warning tags are 'network', 'deprecated', 'experimental'
core:update_policy: (Legacy). If equal 'legacy' when multiple remotes, update based on order of remotes, only the timestamp of the first occurrence of each revision counts.
core:warnings_as_errors: Treat warnings matching any of the patterns in this list as errors and then raise an exception. Current warning tags are 'network', 'deprecated'
tools.android:cmake_legacy_toolchain: Define to explicitly pass ANDROID_USE_LEGACY_TOOLCHAIN_FILE in CMake toolchain
tools.android:ndk_path: Argument for the CMAKE_ANDROID_NDK
tools.apple:enable_arc: (boolean) Enable/Disable ARC Apple Clang flags
tools.apple:enable_bitcode: (boolean) Enable/Disable Bitcode Apple Clang flags
tools.apple:enable_visibility: (boolean) Enable/Disable Visibility Apple Clang flags
tools.apple:sdk_path: Path to the SDK to be used
tools.build.cross_building:can_run: (boolean) Indicates whether is possible to run a non-native app on the same architecture. It's used by 'can_run' tool
tools.build.cross_building:cross_build: (boolean) Decides whether cross-building or not regardless of arch/OS settings. Used by 'cross_building' tool
tools.build:cflags: List of extra C flags used by different toolchains like CMakeToolchain, AutotoolsToolchain and MesonToolchain
tools.build:compiler_executables: Defines a Python dict-like with the compilers path to be used. Allowed keys {'c', 'cpp', 'cuda', 'objc', 'objcxx', 'rc', 'fortran', 'asm', 'hip', 'ispc'}
tools.build:cxxflags: List of extra CXX flags used by different toolchains like CMakeToolchain, AutotoolsToolchain and MesonToolchain
tools.build:defines: List of extra definition flags used by different toolchains like CMakeToolchain, AutotoolsToolchain and MesonToolchain
tools.build:download_source: Force download of sources for every package
tools.build:exelinkflags: List of extra flags used by different toolchains like CMakeToolchain, AutotoolsToolchain and MesonToolchain
tools.build:install_strip: (boolean) Strip the binaries when installing them with CMake, Meson and Autotools
tools.build:jobs: Default compile jobs number -jX Ninja, Make, /MP VS (default: max CPUs)
tools.build:linker_scripts: List of linker script files to pass to the linker used by different toolchains like CMakeToolchain, AutotoolsToolchain, and MesonToolchain
tools.build:sharedlinkflags: List of extra flags used by different toolchains like CMakeToolchain, AutotoolsToolchain and MesonToolchain
tools.build:skip_test: Do not execute CMake.test() and Meson.test() when enabled
tools.build:sysroot: Pass the --sysroot=<tools.build:sysroot> flag if available. (None by default)
tools.build:verbosity: Verbosity of build systems if set. Possible values are 'quiet' and 'verbose'
tools.cmake.cmake_layout:build_folder: (Experimental) Allow configuring the base folder of the build for local builds
tools.cmake.cmake_layout:build_folder_vars: Settings and Options that will produce a different build folder and different CMake presets names
tools.cmake.cmake_layout:test_folder: (Experimental) Allow configuring the base folder of the build for test_package
tools.cmake.cmakedeps:new: Use the new CMakeDeps generator
tools.cmake.cmaketoolchain:enabled_blocks: Select the specific blocks to use in the conan_toolchain.cmake
tools.cmake.cmaketoolchain:extra_variables: Dictionary with variables to be injected in CMakeToolchain (potential override of CMakeToolchain defined variables)
tools.cmake.cmaketoolchain:find_package_prefer_config: Argument for the CMAKE_FIND_PACKAGE_PREFER_CONFIG
tools.cmake.cmaketoolchain:generator: User defined CMake generator to use instead of default
tools.cmake.cmaketoolchain:presets_environment: String to define wether to add or not the environment section to the CMake presets. Empty by default, will generate the environment section in CMakePresets. Can take values: 'disabled'.
tools.cmake.cmaketoolchain:system_name: Define CMAKE_SYSTEM_NAME in CMakeToolchain
tools.cmake.cmaketoolchain:system_processor: Define CMAKE_SYSTEM_PROCESSOR in CMakeToolchain
tools.cmake.cmaketoolchain:system_version: Define CMAKE_SYSTEM_VERSION in CMakeToolchain
tools.cmake.cmaketoolchain:toolchain_file: Use other existing file rather than conan_toolchain.cmake one
tools.cmake.cmaketoolchain:toolset_arch: Toolset architecture to be used as part of CMAKE_GENERATOR_TOOLSET in CMakeToolchain
tools.cmake.cmaketoolchain:toolset_cuda: (Experimental) Path to a CUDA toolset to use, or version if installed at the system level
tools.cmake.cmaketoolchain:user_presets: (Experimental) Select a different name instead of CMakeUserPresets.json, empty to disable
tools.cmake.cmaketoolchain:user_toolchain: Inject existing user toolchains at the beginning of conan_toolchain.cmake
tools.cmake:cmake_program: Path to CMake executable
tools.cmake:install_strip: (Deprecated) Add --strip to cmake.install(). Use tools.build:install_strip instead
tools.compilation:verbosity: Verbosity of compilation tools if set. Possible values are 'quiet' and 'verbose'
tools.deployer:symlinks: Set to False to disable deployers copying symlinks
tools.env.virtualenv:powershell: If specified, it generates PowerShell launchers (.ps1). Use this configuration setting the PowerShell executable you want to use (e.g., 'powershell.exe' or 'pwsh'). Setting it to True or False is deprecated as of Conan 2.11.0.
tools.env:dotenv: (Experimental) Generate dotenv environment files
tools.files.download:retry: Number of retries in case of failure when downloading
tools.files.download:retry_wait: Seconds to wait between download attempts
tools.files.download:verify: If set, overrides recipes on whether to perform SSL verification for their downloaded files. Only recommended to be set while testing
tools.files.unzip:filter: Define tar extraction filter: 'fully_trusted', 'tar', 'data'
tools.gnu:build_triplet: Custom build triplet to pass to Autotools scripts
tools.gnu:define_libcxx11_abi: Force definition of GLIBCXX_USE_CXX11_ABI=1 for libstdc++11
tools.gnu:extra_configure_args: List of extra arguments to pass to configure when using AutotoolsToolchain and GnuToolchain
tools.gnu:host_triplet: Custom host triplet to pass to Autotools scripts
tools.gnu:make_program: Indicate path to make program
tools.gnu:pkg_config: Path to pkg-config executable used by PkgConfig build helper
tools.google.bazel:bazelrc_path: List of paths to bazelrc files to be used as 'bazel --bazelrc=rcpath1 ... build'
tools.google.bazel:configs: List of Bazel configurations to be used as 'bazel build --config=config1 ...'
tools.graph:skip_binaries: Allow the graph to skip binaries not needed in the current configuration (True by default)
tools.graph:skip_build: (Experimental) Do not expand build/tool_requires
tools.graph:skip_test: (Experimental) Do not expand test_requires. If building it might need 'tools.build:skip_test=True'
tools.graph:vendor: (Experimental) If 'build', enables the computation of dependencies of vendoring packages to build them
tools.info.package_id:confs: List of existing configuration to be part of the package ID
tools.intel:installation_path: Defines the Intel oneAPI installation root path
tools.intel:setvars_args: Custom arguments to be passed onto the setvars.sh|bat script from Intel oneAPI
tools.meson.mesontoolchain:backend: Any Meson backend: ninja, vs, vs2010, vs2012, vs2013, vs2015, vs2017, vs2019, xcode
tools.meson.mesontoolchain:extra_machine_files: List of paths for any additional native/cross file references to be appended to the existing Conan ones
tools.microsoft.bash:active: Set True only when Conan runs in a POSIX Bash (MSYS2/Cygwin) where Python's subprocess (shell=True) uses a POSIX-compatible shell (e.g., /bin/sh). Do not set when using Conan from cmd/PowerShell or with native Windows Python ('win32').
tools.microsoft.bash:path: The path to the shell to run when conanfile.win_bash==True
tools.microsoft.bash:subsystem: The subsystem to be used when conanfile.win_bash==True. Possible values: msys2, msys, cygwin, wsl, sfu
tools.microsoft.msbuild:installation_path: VS install path, to avoid auto-detect via vswhere, like C:/Program Files (x86)/Microsoft Visual Studio/2019/Community. Use empty string to disable
tools.microsoft.msbuild:max_cpu_count: Argument for the /m when running msvc to build parallel projects
tools.microsoft.msbuild:vs_version: Defines the IDE version (15, 16, 17) when using the msvc compiler. Necessary if compiler.version specifies a toolset that is not the IDE default
tools.microsoft.msbuilddeps:exclude_code_analysis: Suppress MSBuild code analysis for patterns
tools.microsoft.msbuildtoolchain:compile_options: Dictionary with MSBuild compiler options
tools.microsoft:msvc_update: Force the specific update irrespective of compiler.update (CMakeToolchain and VCVars)
tools.microsoft:winsdk_version: Use this winsdk_version in vcvars
tools.system.package_manager:mode: Mode for package_manager tools: 'check', 'report', 'report-installed' or 'install'
tools.system.package_manager:sudo: Use 'sudo' when invoking the package manager tools in Linux (False by default)
tools.system.package_manager:sudo_askpass: Use the '-A' argument if using sudo in Linux to invoke the system package manager (False by default)
tools.system.package_manager:tool: Default package manager tool: 'apk', 'apt-get', 'yum', 'dnf', 'brew', 'pacman', 'choco', 'zypper', 'pkg' or 'pkgutil'

用户/工具配置

工具和用户配置可以在 global.conf 文件和 Conan profiles 中定义。它们看起来像：

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

重要

Profiles 中的值将优先于 global.conf 中全局定义的值。

以下是一些关于配置项范围和命名的提示：

  • core.xxx 和 tools.yyy 是 Conan 内置的，用户不能在这些范围内定义自己的。

  • core.xxx 只能在 global.conf 或通过 --core-conf CLI 参数定义，但不能在 profiles 中定义。

  • tools.yyy 可以在 global.conf、profiles 的 [conf] 部分以及 CLI -c 参数中定义。

  • user.zzz 可以在任何地方定义，并且完全由用户自行决定，没有固定的命名约定。但是，以下约定会比较常见：

    • 对于开源库，特别是 conancenter 中的库，可能会期望使用 user.packagename:conf，例如 boost recipe 定义 user.boost:conf conf。

    • 对于私有使用，建议使用类似 user.orgname:conf 的方式来为所有项目进行全局组织配置，使用 user.orgname.project:conf 来进行项目或包配置，尽管如果项目名称足够独特，user.project:conf 也可能不错。

    • 它们 _必须_ 包含一个 : 分隔符，例如 user.myorg:conf，但不能是 user.myorg.conf 或 user.myorg。这是为了区分下面的 patterns。

配置文件模板

可以使用 jinja2 模板引擎来处理 global.conf。当 Conan 加载此文件时，它会立即解析并渲染模板，结果必须是标准的工具配置文本。

# Using all the cores automatically
tools.build:jobs={{os.cpu_count()}}
# Using the current OS
user.myconf.system:name = {{platform.system()}}

Conan 还会将 detect_api (不稳定，请阅读参考文档) 注入到 jinja 渲染上下文中。您可以使用如下方式：

user.myteam:myconf1={{detect_api.detect_os()}}
user.myteam:myconf2={{detect_api.detect_arch()}}

有关如何使用的更多信息，请参阅 profiles 参考文档中的 detect_api 部分。

用于渲染模板的 Python 包包括 os 和 platform (适用于所有平台) 以及 Linux 平台上的 distro。此外，变量 conan_version 和 conan_home_folder 也可用。

配置数据类型

Conan 将所有值解释为 Python 内置函数 eval() 的结果。

# String
tools.build:verbosity=verbose
# Boolean
tools.system.package_manager:sudo=True
# Integer
tools.microsoft.msbuild:max_cpu_count=2
# List of values
user.myconf.build:ldflags=["--flag1", "--flag2"]
# Dictionary
tools.microsoft.msbuildtoolchain:compile_options={"ExceptionHandling": "Async"}

配置数据运算符

在 global.conf 或任何 profiles 中组合工具配置时，还可以使用一些额外的运算符：

  • += == append: 将值附加到现有值之后 (仅适用于列表)。

  • =+ == prepend: 将值放在现有值之前 (仅适用于列表)。

  • *= == update: 仅更新指定键，其余保持不变 (仅适用于字典)。

  • =! == unset: 移除任何配置值。

global.conf
# Define the value => ["-f1"]
user.myconf.build:flags=["-f1"]

# Append the value ["-f2"] => ["-f1", "-f2"]
user.myconf.build:flags+=["-f2"]

# Prepend the value ["-f0"] => ["-f0", "-f1", "-f2"]
user.myconf.build:flags=+["-f0"]

# Unset the value
user.myconf.build:flags=!

# Define the value => {"a": 1, "b": 2}
user.myconf.build:other={"a": 1, "b": 2}

# Update b = 4 => {"a": 1, "b": 4}
user.myconf.build:other*={"b": 4}

配置 patterns

您可以使用包 patterns 来将配置应用于匹配的依赖项。

*:tools.cmake.cmaketoolchain:generator=Ninja
zlib/*:tools.cmake.cmaketoolchain:generator=Visual Studio 16 2019

此示例显示了如何为除 zlib 以外的所有包指定通用的 generator，而 zlib 则将其 generator 定义为 Visual Studio 16 2019。

此外，非常重要的一点是：顺序很重要。因此，如果我们更改上面配置行的顺序：

zlib/*:tools.cmake.cmaketoolchain:generator=Visual Studio 16 2019
*:tools.cmake.cmaketoolchain:generator=Ninja

结果是您为所有包指定了一个通用的 generator，仅此而已。 zlib 行无效，因为它是在第一个被评估的，之后，Conan 会用更通用的模式覆盖这个特定的模式，所以需要特别注意顺序。

内置 confs 信息

本节提供有关特定 confs 的额外信息。

网络 confs

客户端证书配置

Conan 支持客户端 TLS 证书。您可以使用以下配置变量来配置指向您现有的 Cacert 文件和/或您的客户端证书 (以及密钥) 的路径：

  • core.net.http:cacert_path: 包含自定义 Cacert 文件的路径。当需要为不同的 remote 准备多个证书时，可以将它们聚合起来，例如添加您自己的 my-ca.crt 证书。

    sudo cp my-ca.crt /usr/local/share/ca-certificates/my-ca.crt
sudo update-ca-certificates

    然后，可以通过 core.net.http:cacert_path=/etc/ssl/certs/ca-certificates.crt 定义证书存储。Conan 的 cacert_path 配置会转发给 python-requests 的 verify 参数，请参阅 Python-requests SSL 证书。这意味着，如果定义了 REQUESTS_CA_BUNDLE 环境变量，也可能会被考虑在内。

  • core.net.http:client_cert: 包含客户端证书 (和密钥) 的文件路径或元组。有关更多详细信息，请参阅 Python requests 和客户端证书。

    例如

    [CONAN_HOME]/global.conf
    core.net.http:client_cert=('/path/client.cert', '/path/client.key')

  • tools.files.download:verify: 将 tools.files.download:verify=False 设置为 False 会禁用证书验证，构成安全风险。除非您了解其含义 (即使那样，将 conf 范围限定到仅所需 recipes 也是个好主意)，或者您只是出于开发目的使用它，否则请勿使用。

代理

有 3 个 confs 可以定义代理信息：

$ conan config list proxies
core.net.http:clean_system_proxy: If defined, the proxies system env-vars will be discarded
core.net.http:no_proxy_match: List of urls to skip from proxies configuration
core.net.http:proxies: Dictionary containing the proxy configuration

core.net.http:proxies 字典会传递给底层的 python-requests 库，作为 "proxies" 参数，如 python-requests 文档 中所述。

core.net:no_proxy_match 是一个 URL patterns 列表，例如：

core.net.http:no_proxy_match = ["http://someurl.com/*"]

用于从 proxies 配置中排除的 URL。这意味着所有引用的、匹配这些 patterns 的 URL 都不会接收 proxies 定义。请注意，pattern 中的 * 对于匹配是必需的。

如果 core.net.http:clean_system_proxy 为 True，则环境变量 "http_proxy", "https_proxy", "ftp_proxy", "all_proxy", "no_proxy" 将被临时移除，因此在解析代理时不会考虑它们。

存储配置

core.cache:storage_path

存储 Conan 包和包数据库的文件夹的绝对路径。该文件夹将是 Conan 最重的存储文件夹，因为它存储了下载或创建的二进制包。

global.conf
core.cache:storage_path = C:\Users\danielm\my_conan_storage_folder

默认值： <CONAN_HOME>/p

core.download:download_cache

存储 Conan 包的文件夹的绝对路径 (压缩 状态)。这对于避免重复下载相同的包很有用，尤其是在 CI 中。

global.conf
core.download:download_cache = C:\Users\danielm\my_download_cache

默认值： 未定义。

UX confs

跳过警告

Conan 在某些情况下会输出一些警告，这些警告可以通过 core:skip_warnings conf 来忽略，方法是将警告标签添加到其值中。

这些警告是：

  • deprecated: 关于已弃用功能的提示，例如旧的 generators。

  • network: 与网络问题相关的提示，例如重试。