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", "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",
"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", "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"]
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"]
watchOS:
version: ["4.0", "4.1", "4.2", "4.3", "5.0", "5.1", "5.2", "5.3", "6.0", "6.1", "6.2",
"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"]
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"]
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"]
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"]
visionOS:
version: ["1.0", "1.1", "1.2"]
sdk: ["xros", "xrsimulator"]
sdk_version: [null, "1.0", "1.1", "1.2"]
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",
"14.0", "14.1", "14.2", "14.3", "14.4", "14.5"]
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"]
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]
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",
"12", "12.1", "12.2", "12.3", "12.4",
"13", "13.1", "13.2", "13.3",
"14", "14.1"]
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]
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"]
libcxx: [null, libstdc++, libstdc++11, libc++, c++_shared, c++_static]
cppstd: [null, 98, gnu98, 11, gnu11, 14, gnu14, 17, gnu17, 20, gnu20, 23, gnu23]
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"]
libcxx: [libstdc++, libc++]
cppstd: [null, 98, gnu98, 11, gnu11, 14, gnu14, 17, gnu17, 20, gnu20, 23, gnu23]
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 2015msvc
compiler version ‘191’: Visual Studio 15 2017msvc
compiler version ‘192’: Visual Studio 16 2019msvc
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.