settings.yml

settings.yml

This configuration file is located in the Conan user home, i.e., [CONAN_HOME]/settings.yml. It looks like this:

# This file was generated by Conan. Remove this comment if you edit this file or Conan
# will destroy your changes.
os:
    Windows:
        subsystem: [null, cygwin, msys, msys2, wsl]
    WindowsStore:
        version: ["8.1", "10.0"]
    WindowsCE:
        platform: [ANY]
        version: ["5.0", "6.0", "7.0", "8.0"]
    Linux:
    iOS:
        version: &ios_version
                   ["7.0", "7.1", "8.0", "8.1", "8.2", "8.3", "8.4", "9.0", "9.1", "9.2", "9.3",
                    "10.0", "10.1", "10.2", "10.3",
                    "11.0", "11.1", "11.2", "11.3", "11.4",
                    "12.0", "12.1", "12.2", "12.3", "12.4", "12.5",
                    "13.0", "13.1", "13.2", "13.3", "13.4", "13.5", "13.6", "13.7",
                    "14.0", "14.1", "14.2", "14.3", "14.4", "14.5", "14.6", "14.7", "14.8",
                    "15.0", "15.1", "15.2", "15.3", "15.4", "15.5", "15.6", "15.7", "15.8",
                    "16.0", "16.1", "16.2", "16.3", "16.4", "16.5", "16.6", "16.7",
                    "17.0", "17.1", "17.2", "17.3", "17.4", "17.5", "17.6", "17.8",
                    "18.0", "18.1"]
        sdk: ["iphoneos", "iphonesimulator"]
        sdk_version: [null, "11.3", "11.4", "12.0", "12.1", "12.2", "12.4",
                        "13.0", "13.1", "13.2", "13.4", "13.5", "13.6", "13.7",
                        "14.0", "14.1", "14.2", "14.3", "14.4", "14.5", "15.0", "15.2", "15.4",
                        "15.5", "16.0", "16.1", "16.2", "16.4", "17.0", "17.1", "17.2", "17.4", "17.5",
                        "18.0", "18.1"]
    watchOS:
        version: ["4.0", "4.1", "4.2", "4.3", "5.0", "5.1", "5.2", "5.3", "6.0", "6.1", "6.2", "6.3",
                    "7.0", "7.1", "7.2", "7.3", "7.4", "7.5", "7.6",
                    "8.0", "8.1", "8.3", "8.4", "8.5", "8.6", "8.7",
                    "9.0","9.1", "9.2", "9.3", "9.4", "9.5", "9.6",
                    "10.0", "10.1", "10.2", "10.3", "10.4", "10.5", "10.6",
                    "11.0", "11.1"]
        sdk: ["watchos", "watchsimulator"]
        sdk_version: [null, "4.3", "5.0", "5.1", "5.2", "5.3", "6.0", "6.1", "6.2",
                        "7.0", "7.1", "7.2", "7.4", "8.0", "8.0.1", "8.3", "8.5", "9.0", "9.1",
                        "9.4", "10.0", "10.1", "10.2", "10.4", "10.5", "11.0", "11.1"]
    tvOS:
        version: ["11.0", "11.1", "11.2", "11.3", "11.4",
                    "12.0", "12.1", "12.2", "12.3", "12.4",
                    "13.0", "13.2", "13.3", "13.4",
                    "14.0", "14.2", "14.3", "14.4", "14.5", "14.6", "14.7",
                    "15.0", "15.1", "15.2", "15.3", "15.4", "15.5", "15.6",
                    "16.0", "16.1", "16.2", "16.3", "16.4", "16.5", "16.6",
                    "17.0", "17.1", "17.2", "17.3", "17.4", "17.5", "17.6",
                    "18.0", "18.1"]
        sdk: ["appletvos", "appletvsimulator"]
        sdk_version: [null, "11.3", "11.4", "12.0", "12.1", "12.2", "12.4",
                        "13.0", "13.1", "13.2", "13.4", "14.0", "14.2", "14.3", "14.5", "15.0",
                        "15.2", "15.4", "16.0", "16.1", "16.4", "17.0", "17.1", "17.2", "17.4", "17.5",
                        "18.0", "18.1"]
    visionOS:
        version: ["1.0", "1.1", "1.2", "2.0", "2.1"]
        sdk: ["xros", "xrsimulator"]
        sdk_version: [null, "1.0", "1.1", "1.2", "2.0", "2.1"]
    Macos:
        version: [null, "10.6", "10.7", "10.8", "10.9", "10.10", "10.11", "10.12", "10.13", "10.14", "10.15",
                    "11.0", "11.1", "11.2", "11.3", "11.4", "11.5", "11.6", "11.7",
                    "12.0", "12.1", "12.2", "12.3", "12.4", "12.5", "12.6", "12.7",
                    "13.0", "13.1", "13.2", "13.3", "13.4", "13.5", "13.6", "13.7",
                    "14.0", "14.1", "14.2", "14.3", "14.4", "14.5", "14.6", "14.7",
                    "15.0", "15.1"]
        sdk_version: [null, "10.13", "10.14", "10.15", "11.0", "11.1", "11.3", "12.0", "12.1",
                        "12.3", "13.0", "13.1", "13.3", "14.0", "14.2", "14.4", "14.5",
                        "15.0", "15.1"]
        subsystem:
            null:
            catalyst:
                ios_version: *ios_version
    Android:
        api_level: [ANY]
        ndk_version: [null, ANY]
    FreeBSD:
    SunOS:
    AIX:
    Arduino:
        board: [ANY]
    Emscripten:
    Neutrino:
        version: ["6.4", "6.5", "6.6", "7.0", "7.1"]
    baremetal:
    VxWorks:
        version: ["7"]
arch: [x86, x86_64, ppc32be, ppc32, ppc64le, ppc64,
       armv4, armv4i, armv5el, armv5hf, armv6, armv7, armv7hf, armv7s, armv7k, armv8, armv8_32, armv8.3, arm64ec,
       sparc, sparcv9,
       mips, mips64, avr, s390, s390x, asm.js, wasm, sh4le,
       e2k-v2, e2k-v3, e2k-v4, e2k-v5, e2k-v6, e2k-v7,
       riscv64, riscv32,
       xtensalx6, xtensalx106, xtensalx7,
       tc131, tc16, tc161, tc162, tc18]
compiler:
    sun-cc:
        version: ["5.10", "5.11", "5.12", "5.13", "5.14", "5.15"]
        threads: [null, posix]
        libcxx: [libCstd, libstdcxx, libstlport, libstdc++]
    gcc:
        version: ["4.1", "4.4", "4.5", "4.6", "4.7", "4.8", "4.9",
                    "5", "5.1", "5.2", "5.3", "5.4", "5.5",
                    "6", "6.1", "6.2", "6.3", "6.4", "6.5",
                    "7", "7.1", "7.2", "7.3", "7.4", "7.5",
                    "8", "8.1", "8.2", "8.3", "8.4", "8.5",
                    "9", "9.1", "9.2", "9.3", "9.4", "9.5",
                    "10", "10.1", "10.2", "10.3", "10.4", "10.5",
                    "11", "11.1", "11.2", "11.3", "11.4", "11.5",
                    "12", "12.1", "12.2", "12.3",  "12.4",
                    "13", "13.1", "13.2", "13.3",
                    "14", "14.1", "14.2"]
        libcxx: [libstdc++, libstdc++11]
        threads: [null, posix, win32]  # Windows MinGW
        exception: [null, dwarf2, sjlj, seh]  # Windows MinGW
        cppstd: [null, 98, gnu98, 11, gnu11, 14, gnu14, 17, gnu17, 20, gnu20, 23, gnu23, 26, gnu26]
        cstd: [null, 99, gnu99, 11, gnu11, 17, gnu17, 23, gnu23]
    msvc:
        version: [170, 180, 190, 191, 192, 193, 194]
        update: [null, 0, 1, 2, 3, 4, 5, 6, 7, 8, 9]
        runtime: [static, dynamic]
        runtime_type: [Debug, Release]
        cppstd: [null, 14, 17, 20, 23]
        toolset: [null, v110_xp, v120_xp, v140_xp, v141_xp]
        cstd: [null, 11, 17]
    clang:
        version: ["3.3", "3.4", "3.5", "3.6", "3.7", "3.8", "3.9", "4.0",
                  "5.0", "6.0", "7.0", "7.1",
                  "8", "9", "10", "11", "12", "13", "14", "15", "16", "17", "18", "19"]
        libcxx: [null, libstdc++, libstdc++11, libc++, c++_shared, c++_static]
        cppstd: [null, 98, gnu98, 11, gnu11, 14, gnu14, 17, gnu17, 20, gnu20, 23, gnu23, 26, gnu26]
        runtime: [null, static, dynamic]
        runtime_type: [null, Debug, Release]
        runtime_version: [null, v140, v141, v142, v143, v144]
        cstd: [null, 99, gnu99, 11, gnu11, 17, gnu17, 23, gnu23]
    apple-clang:
        version: ["5.0", "5.1", "6.0", "6.1", "7.0", "7.3", "8.0", "8.1", "9.0", "9.1",
                  "10.0", "11.0", "12.0", "13", "13.0", "13.1", "14", "14.0", "15", "15.0", "16", "16.0"]
        libcxx: [libstdc++, libc++]
        cppstd: [null, 98, gnu98, 11, gnu11, 14, gnu14, 17, gnu17, 20, gnu20, 23, gnu23, 26, gnu26]
        cstd: [null, 99, gnu99, 11, gnu11, 17, gnu17, 23, gnu23]
    intel-cc:
        version: ["2021.1", "2021.2", "2021.3", "2021.4", "2022.1", "2022.2",
                  "2022.3", "2023.0", "2023.1", "2023.2", "2024.0",]
        update: [null, ANY]
        mode: ["icx", "classic", "dpcpp"]
        libcxx: [null, libstdc++, libstdc++11, libc++]
        cppstd: [null, 98, gnu98, "03", gnu03, 11, gnu11, 14, gnu14, 17, gnu17, 20, gnu20, 23, gnu23]
        runtime: [null, static, dynamic]
        runtime_type: [null, Debug, Release]
    qcc:
        version: ["4.4", "5.4", "8.3"]
        libcxx: [cxx, gpp, cpp, cpp-ne, accp, acpp-ne, ecpp, ecpp-ne]
        cppstd: [null, 98, gnu98, 11, gnu11, 14, gnu14, 17, gnu17]
    mcst-lcc:
        version: ["1.19", "1.20", "1.21", "1.22", "1.23", "1.24", "1.25"]
        libcxx: [libstdc++, libstdc++11]
        cppstd: [null, 98, gnu98, 11, gnu11, 14, gnu14, 17, gnu17, 20, gnu20, 23, gnu23]
build_type: [null, Debug, Release, RelWithDebInfo, MinSizeRel]

As you can see, the possible values of settings are defined in the same file. This is done to ensure matching naming and spelling as well as defining a common settings model among users and the OSS community. Some general information about settings:

If a setting is allowed to be set to any value, you can use ANY.
If a setting is allowed to be set to any value or it can also be unset, you can use [null, ANY].

However, this configuration file can be modified to any needs, including new settings or sub-settings and their values. If you want to distribute an unified settings.yml file you can use the conan config install command.

Operating systems

baremetal operating system is a convention meaning that the binaries run directly on the hardware, without an operating system or equivalent layer. This is to differentiate to the null value, which is associated to the “this value is not defined” semantics. baremetal is a common name convention for embedded microprocessors and microcontrollers’ code. It is expected that users might customize the space inside the baremetal setting with further subsettings to specify their specific hardware platforms, boards, families, etc. At the moment the os=baremetal value is still not used by Conan builtin toolchains and helpers, but it is expected that they can evolve and start using it.

Compilers

Some notes about different compilers:

msvc

It uses the compiler version, that is 190 (19.0), 191 (19.1), etc, instead of the Visual Studio IDE (15, 16, etc).
It is only used by the new build integrations in conan.tools.cmake and conan.tools.microsoft, but not the previous ones.

When using the msvc compiler, the Visual Studio toolset version (the actual vcvars activation and MSBuild location) will be defined by the default provided by that compiler version:

msvc compiler version ‘190’: Visual Studio 14 2015
msvc compiler version ‘191’: Visual Studio 15 2017
msvc compiler version ‘192’: Visual Studio 16 2019
msvc compiler version ‘193’: Visual Studio 17 2022

This can be configured in your profiles with the tools.microsoft.msbuild:vs_version configuration:

[settings]
compiler=msvc
compiler.version=190
[conf]
tools.microsoft.msbuild:vs_version = 16

In this case, the vcvars will activate the Visual Studio 16 installation, but the 190 compiler version will still be used because the necessary toolset=v140 will be set.

The settings define the last digit update: [null, 0, 1, 2, 3, 4, 5, 6, 7, 8, 9], which by default is null and means that Conan assumes binary compatibility for the compiler patches, which works in general for the Microsoft compilers. For cases where finer control is desired, you can just add the update part to your profiles:

[settings]
compiler=msvc
compiler.version=191
compiler.update=3

This will be equivalent to the full version 1913 (19.13). If even further details are desired, you could even add your own digits to the update subsetting in settings.yml.

intel-cc

Warning

This feature is experimental and subject to breaking changes. See the Conan stability section for more information.

This compiler is aimed to handle the new Intel oneAPI DPC++/C++/Classic compilers. Instead of having n different compilers, you have 3 different modes of working:

icx for Intel oneAPI C++.
dpcpp for Intel oneAPI DPC++.
classic for Intel C++ Classic ones.

Besides that, Intel releases some versions with revisions numbers so the update field is supposed to be any possible minor number for the Intel compiler version used, e.g, compiler.version=2021.1 and compiler.update=311 mean Intel version is 2021.1.311.

Architectures

Here you can find a brief explanation of each of the architectures defined as arch, arch_build and arch_target settings.

x86: The popular 32 bit x86 architecture.
x86_64: The popular 64 bit x64 architecture.
ppc64le: The PowerPC 64 bit Big Endian architecture.
ppc32: The PowerPC 32 bit architecture.
ppc64le: The PowerPC 64 bit Little Endian architecture.
ppc64: The PowerPC 64 bit Big Endian architecture.
armv5el: The ARM 32 bit version 5 architecture, soft-float.
armv5hf: The ARM 32 bit version 5 architecture, hard-float.
armv6: The ARM 32 bit version 6 architecture.
armv7: The ARM 32 bit version 7 architecture.
armv7hf: The ARM 32 bit version 7 hard-float architecture.
armv7s: The ARM 32 bit version 7 swift architecture mostly used in Apple’s A6 and A6X chips on iPhone 5, iPhone 5C and iPad 4.
armv7k: The ARM 32 bit version 7 k architecture mostly used in Apple’s WatchOS.
armv8: The ARM 64 bit and 32 bit compatible version 8 architecture. It covers only the aarch64 instruction set.
armv8_32: The ARM 32 bit version 8 architecture. It covers only the aarch32 instruction set (a.k.a. ILP32).
armv8.3: The ARM 64 bit and 32 bit compatible version 8.3 architecture. Also known as arm64e, it is used on the A12 chipset added in the latest iPhone models (XS/XS Max/XR).
arm64e: Windows 11 ARM64 (Emulation Compatible). This architecture support is experimental and incomplete. The only usage is to define CMAKE_GENERATOR_PLATFORM in CMake VS generators. Report new issues in Github if necessary.
sparc: The SPARC (Scalable Processor Architecture) originally developed by Sun Microsystems.
sparcv9: The SPARC version 9 architecture.
mips: The 32 bit MIPS (Microprocessor without Interlocked Pipelined Stages) developed by MIPS Technologies (formerly MIPS Computer Systems).
mips64: The 64 bit MIPS (Microprocessor without Interlocked Pipelined Stages) developed by MIPS Technologies (formerly MIPS Computer Systems).
avr: The 8 bit AVR microcontroller architecture developed by Atmel (Microchip Technology).
s390: The 32 bit address Enterprise Systems Architecture 390 from IBM.
s390x: The 64 bit address Enterprise Systems Architecture 390 from IBM.
asm.js: The subset of JavaScript that can be used as low-level target for compilers, not really a processor architecture, it’s produced by Emscripten. Conan treats it as an architecture to align with build systems design (e.g. GNU auto tools and CMake).
wasm: The Web Assembly, not really a processor architecture, but byte-code format for Web, it’s produced by Emscripten. Conan treats it as an architecture to align with build systems design (e.g. GNU auto tools and CMake).
sh4le: The Hitachi SH-4 SuperH architecture.
e2k-v2: The Elbrus 2000 v2 512 bit VLIW (Very Long Instruction Word) architecture (Elbrus 2CM, Elbrus 2C+ CPUs) originally developed by MCST (Moscow Center of SPARC Technologies).
e2k-v3: The Elbrus 2000 v3 512 bit VLIW (Very Long Instruction Word) architecture (Elbrus 2S, aka Elbrus 4C, CPU) originally developed by MCST (Moscow Center of SPARC Technologies).
e2k-v4: The Elbrus 2000 v4 512 bit VLIW (Very Long Instruction Word) architecture (Elbrus 8C, Elbrus 8C1, Elbrus 1C+ and Elbrus 1CK CPUs) originally developed by MCST (Moscow Center of SPARC Technologies).
e2k-v5: The Elbrus 2000 v5 512 bit VLIW (Very Long Instruction Word) architecture (Elbrus 8C2 ,aka Elbrus 8CB, CPU) originally developed by MCST (Moscow Center of SPARC Technologies).
e2k-v6: The Elbrus 2000 v6 512 bit VLIW (Very Long Instruction Word) architecture (Elbrus 2C3, Elbrus 12C and Elbrus 16C CPUs) originally developed by MCST (Moscow Center of SPARC Technologies).
e2k-v7: The Elbrus 2000 v7 512 bit VLIW (Very Long Instruction Word) architecture (Elbrus 32C CPU) originally developed by MCST (Moscow Center of SPARC Technologies).
xtensalx6: Xtensa LX6 DPU for ESP32 microcontroller.
xtensalx106: Xtensa LX6 DPU for ESP8266 microcontroller.
xtensalx7: Xtensa LX7 DPU for ESP32-S2 and ESP32-S3 microcontrollers.

C++ standard libraries (aka compiler.libcxx)

compiler.libcxx sub-setting defines C++ standard libraries implementation to be used. The sub-setting applies only to certain compilers, e.g. it applies to clang, apple-clang and gcc, but doesn’t apply to Visual Studio.

libstdc++ (gcc, clang, apple-clang, sun-cc): The GNU C++ Library. NOTE that this implicitly defines _GLIBCXX_USE_CXX11_ABI=0 to use old ABI. Might be a wise choice for old systems, such as CentOS 6. On Linux systems, you may need to install libstdc++-dev (package name could be different in various distros) in order to use the standard library. NOTE that on Apple systems usage of libstdc++ has been deprecated.
libstdc++11 (gcc, clang, apple-clang): The GNU C++ Library. NOTE that this implicitly defines _GLIBCXX_USE_CXX11_ABI=1 to use new ABI. Might be a wise choice for newer systems, such as Ubuntu 20. On Linux systems, you may need to install libstdc++-dev (package name could be different in various distros) in order to use the standard library. NOTE that on Apple systems usage of libstdc++ has been deprecated.
libc++ (clang, apple-clang): LLVM libc++. On Linux systems, you may need to install libc++-dev (package name could be different in various distros) in order to use the standard library.
c++_shared (clang, Android only): use LLVM libc++ as a shared library. Refer to the C++ Library Support for the additional details.
c++_static (clang, Android only): use LLVM libc++ as a static library. Refer to the C++ Library Support for the additional details.
libCstd (sun-cc): Rogue Wave’s stdlib. See Comparing C++ Standard Libraries libCstd, libstlport, and libstdcxx.
libstlport (sun-cc): STLport. See Comparing C++ Standard Libraries libCstd, libstlport, and libstdcxx.
libstdcxx (sun-cc): Apache C++ Standard Library. See Comparing C++ Standard Libraries libCstd, libstlport, and libstdcxx.
gpp (qcc): GNU C++ lib. See QCC documentation.
cpp (qcc): Dinkum C++ lib. See QCC documentation.
cpp-ne (qcc): Dinkum C++ lib (no exceptions). See QCC documentation.
acpp (qcc): Dinkum Abridged C++ lib. See QCC documentation.
acpp-ne (qcc): Dinkum Abridged C++ lib (no exceptions). See QCC documentation.
ecpp (qcc): Embedded Dinkum C++ lib. See QCC documentation.
ecpp-ne (qcc): Embedded Dinkum C++ lib (no exceptions). See QCC documentation.
cxx (qcc): LLVM C++. See QCC documentation.

Customizing settings

Settings are also customizable to add your own ones:

Adding new settings

It is possible to add new settings at the root of the settings.yml file, something like:

os:
    Windows:
        subsystem: [null, cygwin, msys, msys2, wsl]
distro: [null, RHEL6, CentOS, Debian]

If we want to create different binaries from our recipes defining this new setting, we would need to add to our recipes that:

class Pkg(ConanFile):
    settings = "os", "compiler", "build_type", "arch", "distro"

The value null allows for not defining it (which would be a default value, valid for all the other distros). It is also possible to define values for it in the profiles:

[settings]
os = "Linux"
distro = "CentOS"
compiler = "gcc"

And use their values to affect our build if desired:

class Pkg(ConanFile):
    settings = "os", "compiler", "build_type", "arch", "distro"
    def generate(self):
        tc = CMakeToolchain(self)
        if self.settings.distro == "CentOS":
            tc.cache_variables["SOME_CENTOS_FLAG"] = "Some CentOS Value"
            ...

Adding new sub-settings

The above approach requires modification to all recipes to take it into account. It is also possible to define kind of incompatible settings, like os=Windows and distro=CentOS. While adding new settings is totally suitable, it might make more sense to add it as a new sub-setting of the Linux OS:

os:
    Windows:
        subsystem: [null, cygwin, msys, msys2, wsl]
    Linux:
        distro: [null, RHEL6, CentOS, Debian]

With this definition we could define our profiles as:

[settings]
os = "Linux"
os.distro = "CentOS"
compiler = "gcc"

And any attempt to define os.distro for another os value rather than Linux will raise an error.

As this is a sub-setting, it will be automatically taken into account in all recipes that declare an os setting. Note that having a value of distro=null possible is important if you want to keep previously created binaries, otherwise you would be forcing to always define a specific distro value, and binaries created without this sub-setting, won’t be usable anymore.

The sub-setting can also be accessed from recipes:

class Pkg(ConanFile):
    settings = "os", "compiler", "build_type", "arch"  # Note, no "distro" defined here
    def generate(self):
        tc = CMakeToolchain(self)
        if self.settings.os == "Linux" and self.settings.os.distro == "CentOS":
            tc.cache_variables["SOME_CENTOS_FLAG"] = "Some CentOS Value"

It is possible to have ANY to define nested subsettings, being the ANY the fallback for any value not matching the defined ones:

os:
    ANY:
        version: [null, ANY]
    Ubuntu:
        version: ["18.04", "20.04"]

This will allow settings like -s os=MyOS -s os.version=1.2.3, because the version can be ANY for os!=Ubuntu, but if we try -s os=Ubuntu -s os.version=1.2.3 it will error because Ubuntu only accept those defined versions.

Add new values

In the same way we have added a new distro sub-setting, it is possible to add new values to existing settings and sub-settings. For example, if some compiler version is not present in the range of accepted values, you can add those new values.

You can also add a completely new compiler:

os:
    Windows:
        subsystem: [null, cygwin, msys, msys2, wsl]
   ...
compiler:
    gcc:
        ...
    mycompiler:
        version: [1.1, 1.2]
    msvc:

This works as the above regarding profiles, and the way they can be accessed from recipes. The main issue with custom compilers is that the builtin build helpers, like CMake, MSBuild, etc, internally contains code that will check for those values. For example, the MSBuild build helper will only know how to manage the msvc setting and sub-settings, but not the new compiler. For those cases, custom logic can be implemented in the recipes:

class Pkg(ConanFile):
    settings = "os", "compiler", "build_type", "arch"
    def build(self):
        if self.settings.compiler == "mycompiler":
            my_custom_compile = ["some", "--flags", "for", "--my=compiler"]
            self.run(["mycompiler", "."] + my_custom_compile)

Note

You can remove items from settings.yml file: compilers, OS, architectures, etc. Do that only in the case you really want to protect against creation of binaries for other platforms other than your main supported ones. In the general case, you can leave them, the binary configurations are managed in profiles, and you want to define your supported configurations in profiles, not by restricting the settings.yml

Note

If you customize your settings.yml, you can share, distribute and sync this configuration with your team and CI machines with the conan config install command.

settings_user.yml

The previous section explains how to customize the Conan settings.yml, but you could also create your settings_user.yml. This file will contain only the new fields-values that you want to use in your recipes, so the final result will be a composition of both files, the settings.yml and the settings_user.yml.