global.conf

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

配置简介

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

  • 包 ID 模式。

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

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

  • 相关工具配置（由工具链、助手等使用）

  • 其他（所需的 Conan 版本、CLI 非交互式等）

让我们简要解释三种现有的配置类型

  • core.*：旨在配置 Conan 核心行为的值（下载重试、包 ID 模式等）。仅可在 global.conf 文件中定义。

  • tools.*：旨在配置配方中使用的 Conan 工具（工具链、构建助手等）的值。可在 global.conf 和 配置文件 中定义。

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

要列出所有可用的配置，请运行 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: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: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: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_toolchain: Inject existing user toolchains at the beginning of conan_toolchain.cmake
tools.cmake:cmake_program: Path to CMake executable
tools.cmake:install_strip: Add --strip to cmake.install()
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 it is set to True it will generate powershell launchers if os=Windows
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: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: If Conan is already running inside bash terminal in Windows
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'

配置描述

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.cache.download_cache = C:\Users\danielm\my_download_cache

默认值：未定义。

用户/工具配置

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

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

重要

配置文件的值将优先于 global.conf 中全局定义的值。

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

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

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

  • tools.yyy 可以在 global.conf、配置文件的 [conf] 部分以及作为 CLI -c 参数定义

  • user.zzz 可以在任何地方定义，并且完全由用户决定，没有既定的命名约定。但是，这或多或少是预期的

    • 对于开源库，特别是 conancenter 中的库，可能需要使用 user.packagename:conf，例如定义 user.boost:conf 配置的 boost 配方

    • 对于私有用途，建议使用类似 user.orgname:conf 来进行所有项目的全局组织配置，user.orgname.project:conf 来进行项目或包配置，尽管如果项目名称足够唯一，user.project:conf 也可以。

    • 它们_必须_有一个 : 分隔符，例如 user.myorg:conf，而不是 user.myorg.conf 或 user.myorg。这是为了与下面讨论的模式区分开来。

配置文件模板

可以使用 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()}}

有关如何使用它的更多信息，请查看配置文件参考中的 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 或任何配置文件中组合工具配置时，还可以使用一些额外的运算符

  • += == 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}

配置模式

您可以使用包模式将配置应用于匹配的依赖项

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

此示例演示了如何为所有包指定一个通用的 generator，除了 zlib，它将 Visual Studio 16 2019 作为其生成器。

此外，必须说 **顺序很重要**。因此，如果我们更改上面配置行的顺序

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

结果是您为所有包指定了一个通用的 generator，仅此而已。zlib 行无效，因为它是最先评估的行，之后 Conan 会用最通用的模式覆盖该特定模式，因此值得特别注意顺序。

内置配置信息

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

网络配置

客户端证书配置

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

  • core.net.http:cacert_path：包含自定义 Cacert 文件的路径。

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

例如

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

另请参阅

  • tools.files.download:verify：如果启用 tools.files.download:verify=False，则会带来安全风险，因为它会禁用证书验证。除非您了解其含义（即使那样，将配置范围限定到仅所需的配方也是一个好主意）或出于开发目的，否则请勿使用它。

UX 配置

跳过警告

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

这些警告是

  • deprecated：有关已弃用功能（例如旧版生成器）的消息

  • network：与网络问题（例如重试）相关的消息