|
| 1 | +.. _reference_config_files_global_conf: |
| 2 | + |
| 3 | +global.conf |
| 4 | +=========== |
| 5 | + |
| 6 | +The **global.conf** file is located in the Conan user home directory, e.g., *[CONAN_HOME]/global.conf*. |
| 7 | + |
| 8 | +Introduction to configuration |
| 9 | +----------------------------- |
| 10 | + |
| 11 | +*global.conf* is aimed to save some core/tools/user configuration variables that will be used by Conan. For instance: |
| 12 | + |
| 13 | +* Package ID modes. |
| 14 | +* General HTTP(python-requests) configuration. |
| 15 | +* Number of retries when downloading/uploading recipes. |
| 16 | +* Related tools configurations (used by toolchains, helpers, etc.) |
| 17 | +* Others (required Conan version, CLI non-interactive, etc.) |
| 18 | + |
| 19 | +Let's briefly explain the three types of existing configurations: |
| 20 | + |
| 21 | +* ``core.*``: aimed to configure values of Conan core behavior (download retries, package ID modes, etc.). |
| 22 | + Only definable in *global.conf* file. |
| 23 | +* ``tools.*``: aimed to configure values of Conan tools (toolchains, build helpers, etc.) used in your recipes. |
| 24 | + Definable in both *global.conf* and *profiles*. |
| 25 | +* ``user.*``: aimed to define personal user configurations. They can define whatever user wants. |
| 26 | + Definable in both *global.conf* and *profiles*. |
| 27 | + |
| 28 | + |
| 29 | + |
| 30 | +To list all the possible configurations available, run :command:`conan config list`: |
| 31 | + |
| 32 | +.. code-block:: text |
| 33 | +
|
| 34 | + $ conan config list |
| 35 | +
|
| 36 | + core.cache:storage_path: Absolute path where the packages and database are stored |
| 37 | + core.download:download_cache: Define path to a file download cache |
| 38 | + core.download:parallel: Number of concurrent threads to download packages |
| 39 | + core.download:retry: Number of retries in case of failure when downloading from Conan server |
| 40 | + core.download:retry_wait: Seconds to wait between download attempts from Conan server |
| 41 | + core.gzip:compresslevel: The Gzip compresion level for Conan artifacts (default=9) |
| 42 | + core.net.http:cacert_path: Path containing a custom Cacert file |
| 43 | + core.net.http:clean_system_proxy: If defined, the proxies system env-vars will be discarded |
| 44 | + core.net.http:client_cert: Path or tuple of files containing a client cert (and key) |
| 45 | + core.net.http:max_retries: Maximum number of connection retries (requests library) |
| 46 | + core.net.http:no_proxy_match: List of urls to skip from proxies configuration |
| 47 | + core.net.http:proxies: Dictionary containing the proxy configuration |
| 48 | + core.net.http:timeout: Number of seconds without response to timeout (requests library) |
| 49 | + core.package_id:default_build_mode: By default, 'None' |
| 50 | + core.package_id:default_embed_mode: By default, 'full_mode' |
| 51 | + core.package_id:default_non_embed_mode: By default, 'minor_mode' |
| 52 | + core.package_id:default_python_mode: By default, 'minor_mode' |
| 53 | + core.package_id:default_unknown_mode: By default, 'semver_mode' |
| 54 | + core.upload:retry: Number of retries in case of failure when uploading to Conan server |
| 55 | + core.upload:retry_wait: Seconds to wait between upload attempts to Conan server |
| 56 | + core:allow_uppercase_pkg_names: Temporarily (will be removed in 2.X) allow uppercase names |
| 57 | + core:default_build_profile: Defines the default build profile (None by default) |
| 58 | + core:default_profile: Defines the default host profile ('default' by default) |
| 59 | + core:non_interactive: Disable interactive user input, raises error if input necessary |
| 60 | + core:required_conan_version: Raise if current version does not match the defined range. |
| 61 | + tools.android:ndk_path: Argument for the CMAKE_ANDROID_NDK |
| 62 | + tools.apple.xcodebuild:verbosity: Verbosity level for xcodebuild: 'verbose' or 'quiet |
| 63 | + tools.apple:enable_arc: (boolean) Enable/Disable ARC Apple Clang flags |
| 64 | + tools.apple:enable_bitcode: (boolean) Enable/Disable Bitcode Apple Clang flags |
| 65 | + tools.apple:enable_visibility: (boolean) Enable/Disable Visibility Apple Clang flags |
| 66 | + tools.apple:sdk_path: Path to the SDK to be used |
| 67 | + tools.build.cross_building:can_run: Bool value that indicates whether is possible to run a non-native app on the same architecture. It's used by 'can_run' tool |
| 68 | + tools.build:cflags: List of extra C flags used by different toolchains like CMakeToolchain, AutotoolsToolchain and MesonToolchain |
| 69 | + 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'} |
| 70 | + tools.build:cxxflags: List of extra CXX flags used by different toolchains like CMakeToolchain, AutotoolsToolchain and MesonToolchain |
| 71 | + tools.build:defines: List of extra definition flags used by different toolchains like CMakeToolchain and AutotoolsToolchain |
| 72 | + tools.build:download_source: Force download of sources for every package |
| 73 | + tools.build:exelinkflags: List of extra flags used by CMakeToolchain for CMAKE_EXE_LINKER_FLAGS_INIT variable |
| 74 | + tools.build:jobs: Default compile jobs number -jX Ninja, Make, /MP VS (default: max CPUs) |
| 75 | + tools.build:linker_scripts: List of linker script files to pass to the linker used by different toolchains like CMakeToolchain, AutotoolsToolchain, and MesonToolchain |
| 76 | + tools.build:sharedlinkflags: List of extra flags used by CMakeToolchain for CMAKE_SHARED_LINKER_FLAGS_INIT variable |
| 77 | + tools.build:skip_test: Do not execute CMake.test() and Meson.test() when enabled |
| 78 | + tools.build:sysroot: Pass the --sysroot=<tools.build:sysroot> flag if available. (None by default) |
| 79 | + tools.cmake.cmake_layout:build_folder_vars: Settings and Options that will produce a different build folder and different CMake presets names |
| 80 | + tools.cmake.cmaketoolchain.presets:max_schema_version: Generate CMakeUserPreset.json compatible with the supplied schema version |
| 81 | + tools.cmake.cmaketoolchain:find_package_prefer_config: Argument for the CMAKE_FIND_PACKAGE_PREFER_CONFIG |
| 82 | + tools.cmake.cmaketoolchain:generator: User defined CMake generator to use instead of default |
| 83 | + tools.cmake.cmaketoolchain:system_name: Define CMAKE_SYSTEM_NAME in CMakeToolchain |
| 84 | + tools.cmake.cmaketoolchain:system_processor: Define CMAKE_SYSTEM_PROCESSOR in CMakeToolchain |
| 85 | + tools.cmake.cmaketoolchain:system_version: Define CMAKE_SYSTEM_VERSION in CMakeToolchain |
| 86 | + tools.cmake.cmaketoolchain:toolchain_file: Use other existing file rather than conan_toolchain.cmake one |
| 87 | + tools.cmake.cmaketoolchain:toolset_arch: Toolset architecture to be used as part of CMAKE_GENERATOR_TOOLSET in CMakeToolchain |
| 88 | + tools.cmake.cmaketoolchain:user_toolchain: Inject existing user toolchains at the beginning of conan_toolchain.cmake |
| 89 | + tools.env.virtualenv:powershell: If it is set to True it will generate powershell launchers if os=Windows |
| 90 | + tools.files.download:download_cache: Define the cache folder to store downloads from files.download()/get() |
| 91 | + tools.files.download:retry: Number of retries in case of failure when downloading |
| 92 | + tools.files.download:retry_wait: Seconds to wait between download attempts |
| 93 | + tools.gnu:define_libcxx11_abi: Force definition of GLIBCXX_USE_CXX11_ABI=1 for libstdc++11 |
| 94 | + tools.gnu:host_triplet: Custom host triplet to pass to Autotools scripts |
| 95 | + tools.gnu:make_program: Indicate path to make program |
| 96 | + tools.gnu:pkg_config: Path to pkg-config executable used by PkgConfig build helper |
| 97 | + tools.google.bazel:bazelrc_path: Defines Bazel rc-path |
| 98 | + tools.google.bazel:configs: Define Bazel config file |
| 99 | + tools.info.package_id:confs: List of existing configuration to be part of the package ID |
| 100 | + tools.intel:installation_path: Defines the Intel oneAPI installation root path |
| 101 | + tools.intel:setvars_args: Custom arguments to be passed onto the setvars.sh|bat script from Intel oneAPI |
| 102 | + tools.meson.mesontoolchain:backend: Any Meson backend: ninja, vs, vs2010, vs2012, vs2013, vs2015, vs2017, vs2019, xcode |
| 103 | + tools.meson.mesontoolchain:extra_machine_files: List of paths for any additional native/cross file references to be appended to the existing Conan ones |
| 104 | + tools.microsoft.bash:active: If Conan is already running inside bash terminal in Windows |
| 105 | + tools.microsoft.bash:path: The path to the shell to run when conanfile.win_bash==True |
| 106 | + tools.microsoft.bash:subsystem: The subsystem to be used when conanfile.win_bash==True. Possible values: msys2, msys, cygwin, wsl, sfu |
| 107 | + 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 |
| 108 | + tools.microsoft.msbuild:max_cpu_count: Argument for the /m when running msvc to build parallel projects |
| 109 | + tools.microsoft.msbuild:verbosity: Verbosity level for MSBuild: 'Quiet', 'Minimal', 'Normal', 'Detailed', 'Diagnostic' |
| 110 | + tools.microsoft.msbuild:vs_version: Defines the IDE version when using the new msvc compiler |
| 111 | + tools.microsoft.msbuilddeps:exclude_code_analysis: Suppress MSBuild code analysis for patterns |
| 112 | + tools.microsoft.msbuildtoolchain:compile_options: Dictionary with MSBuild compiler options |
| 113 | + tools.system.package_manager:mode: Mode for package_manager tools: 'check' or 'install' |
| 114 | + tools.system.package_manager:sudo: Use 'sudo' when invoking the package manager tools in Linux (False by default) |
| 115 | + tools.system.package_manager:sudo_askpass: Use the '-A' argument if using sudo in Linux to invoke the system package manager (False by default) |
| 116 | + tools.system.package_manager:tool: Default package manager tool: 'apt-get', 'yum', 'dnf', 'brew', 'pacman', 'choco', 'zypper', 'pkg' or 'pkgutil' |
| 117 | +
|
| 118 | +
|
| 119 | +
|
| 120 | +
|
| 121 | +Tools configurations |
| 122 | +-------------------- |
| 123 | + |
| 124 | +Tools and user configurations allow them to be defined both in the *global.conf* file and in profile files. Profile values will |
| 125 | +have priority over globally defined ones in *global.conf*, and can be defined as: |
| 126 | + |
| 127 | +.. code-block:: text |
| 128 | + :caption: *myprofile* |
| 129 | +
|
| 130 | + [settings] |
| 131 | + ... |
| 132 | +
|
| 133 | + [conf] |
| 134 | + tools.microsoft.msbuild:verbosity=Diagnostic |
| 135 | + tools.microsoft.msbuild:max_cpu_count=2 |
| 136 | + tools.microsoft.msbuild:vs_version = 16 |
| 137 | + tools.build:jobs=10 |
| 138 | +
|
| 139 | +
|
| 140 | +Configuration file template |
| 141 | +--------------------------- |
| 142 | + |
| 143 | + |
| 144 | +It is possible to use **jinja2** template engine for *global.conf*. When Conan loads this file, it immediately parses |
| 145 | +and renders the template, which must result in a standard tools-configuration text. |
| 146 | + |
| 147 | + .. code:: jinja |
| 148 | +
|
| 149 | + # Using all the cores automatically |
| 150 | + tools.build:jobs={{os.cpu_count()}} |
| 151 | + # Using the current OS |
| 152 | + user.myconf.system:name = {{platform.system()}} |
| 153 | +
|
| 154 | +
|
| 155 | +The Python packages passed to render the template are ``os`` and ``platform`` for all platforms and ``distro`` in Linux platforms. |
| 156 | + |
| 157 | + |
| 158 | +Configuration data types |
| 159 | +------------------------ |
| 160 | + |
| 161 | + |
| 162 | +All the values will be interpreted by Conan as the result of the python built-in `eval()` function: |
| 163 | + |
| 164 | +.. code-block:: text |
| 165 | +
|
| 166 | + # String |
| 167 | + tools.microsoft.msbuild:verbosity=Diagnostic |
| 168 | + # Boolean |
| 169 | + tools.system.package_manager:sudo=True |
| 170 | + # Integer |
| 171 | + tools.microsoft.msbuild:max_cpu_count=2 |
| 172 | + # List of values |
| 173 | + user.myconf.build:ldflags=["--flag1", "--flag2"] |
| 174 | + # Dictionary |
| 175 | + tools.microsoft.msbuildtoolchain:compile_options={"ExceptionHandling": "Async"} |
| 176 | +
|
| 177 | +
|
| 178 | +Configuration data operators |
| 179 | +---------------------------- |
| 180 | + |
| 181 | + |
| 182 | +It's also possible to use some extra operators when you're composing tool configurations in your *global.conf* or |
| 183 | +any of your profiles: |
| 184 | + |
| 185 | +* ``+=`` == ``append``: appends values at the end of the existing value (only for lists). |
| 186 | +* ``=+`` == ``prepend``: puts values at the beginning of the existing value (only for lists). |
| 187 | +* ``=!`` == ``unset``: gets rid of any configuration value. |
| 188 | + |
| 189 | +.. code-block:: text |
| 190 | + :caption: *myprofile* |
| 191 | +
|
| 192 | + [settings] |
| 193 | + ... |
| 194 | +
|
| 195 | + [conf] |
| 196 | + # Define the value => ["-f1"] |
| 197 | + user.myconf.build:flags=["-f1"] |
| 198 | +
|
| 199 | + # Append the value ["-f2"] => ["-f1", "-f2"] |
| 200 | + user.myconf.build:flags+=["-f2"] |
| 201 | +
|
| 202 | + # Prepend the value ["-f0"] => ["-f0", "-f1", "-f2"] |
| 203 | + user.myconf.build:flags=+["-f0"] |
| 204 | +
|
| 205 | + # Unset the value |
| 206 | + user.myconf.build:flags=! |
| 207 | +
|
| 208 | +
|
| 209 | +Configuration in your profiles |
| 210 | +-------------------------------- |
| 211 | + |
| 212 | +Let's see a little bit more complex example trying different configurations coming from the *global.conf* and a simple profile: |
| 213 | + |
| 214 | +.. code-block:: text |
| 215 | + :caption: *global.conf* |
| 216 | +
|
| 217 | + # Defining several lists |
| 218 | + user.myconf.build:ldflags=["--flag1 value1"] |
| 219 | + user.myconf.build:cflags=["--flag1 value1"] |
| 220 | +
|
| 221 | +
|
| 222 | +.. code-block:: text |
| 223 | + :caption: *myprofile* |
| 224 | +
|
| 225 | + [settings] |
| 226 | + ... |
| 227 | +
|
| 228 | + [conf] |
| 229 | + # Appending values into the existing list |
| 230 | + user.myconf.build:ldflags+=["--flag2 value2"] |
| 231 | +
|
| 232 | + # Unsetting the existing value (it'd be like we define it as an empty value) |
| 233 | + user.myconf.build:cflags=! |
| 234 | +
|
| 235 | + # Prepending values into the existing list |
| 236 | + user.myconf.build:ldflags=+["--prefix prefix-value"] |
| 237 | +
|
| 238 | +
|
| 239 | +Running, for instance, :command:`conan install . -pr myprofile`, the configuration output will be something like: |
| 240 | + |
| 241 | +.. code-block:: bash |
| 242 | +
|
| 243 | + ... |
| 244 | + Configuration: |
| 245 | + [settings] |
| 246 | + [options] |
| 247 | + [tool_requires] |
| 248 | + [conf] |
| 249 | + user.myconf.build:cflags=! |
| 250 | + user.myconf.build:ldflags=['--prefix prefix-value', '--flag1 value1', '--flag2 value2'] |
| 251 | + ... |
| 252 | +
|
| 253 | +
|
| 254 | +Configuration patterns |
| 255 | +---------------------- |
| 256 | + |
| 257 | +You can use package patterns to apply the configuration in those dependencies which are matching: |
| 258 | + |
| 259 | +.. code-block:: text |
| 260 | +
|
| 261 | + *:tools.cmake.cmaketoolchain:generator=Ninja |
| 262 | + zlib:tools.cmake.cmaketoolchain:generator=Visual Studio 16 2019 |
| 263 | +
|
| 264 | +This example shows you how to specify a general ``generator`` for all your packages except for `zlib` which is defining |
| 265 | +`Visual Studio 16 2019` as its generator. |
| 266 | + |
| 267 | +Besides that, it's quite relevant to say that **the order matters**. So, if we change the order of the |
| 268 | +configuration lines above: |
| 269 | + |
| 270 | +.. code-block:: text |
| 271 | +
|
| 272 | + zlib:tools.cmake.cmaketoolchain:generator=Visual Studio 16 2019 |
| 273 | + *:tools.cmake.cmaketoolchain:generator=Ninja |
| 274 | +
|
| 275 | +The result is that you're specifying a general `generator` for all your packages, and that's it. The `zlib` line has no |
| 276 | +effect because it's the first one evaluated, and after that, Conan is overriding that specific pattern with the most |
| 277 | +general one, so it deserves to pay special attention to the order. |
| 278 | + |
| 279 | + |
| 280 | +Configuration of client certificates |
| 281 | +------------------------------------ |
| 282 | + |
| 283 | +Conan supports client TLS certificates. You can configure the path to your existing *Cacert* file and/or your client |
| 284 | +certificate (and the key) using the following configuration variables: |
| 285 | + |
| 286 | +* ``core.net.http:cacert_path``: Path containing a custom Cacert file. |
| 287 | +* ``core.net.http:client_cert``: Path or tuple of files containing a client cert (and key). |
| 288 | + |
| 289 | +For instance: |
| 290 | + |
| 291 | +.. code-block:: text |
| 292 | + :caption: **[CONAN_HOME]/global.conf** |
| 293 | +
|
| 294 | + core.net.http:cacert_path=/path/to/cacert_file |
| 295 | + core.net.http:client_cert=/path/to/client_certificate |
| 296 | +
|
| 297 | +
|
| 298 | +.. seealso:: |
| 299 | + |
| 300 | + * :ref:`Managing configuration in your recipes (self.conf_info) <conan_conanfile_model_conf_info>` |
0 commit comments