Toolchains
Toolchains are the new, experimental way to integrate with build systems in Conan.
Recipes can define a toolchain() method that will return an object which
can generate files from the current configuration that can be used by the build systems.
Conan generators provide information about dependencies, while toolchains provide a
“translation” from the Conan settings and options, and the recipe defined configuration
to something that the build system can understand. A recipe that does not have dependencies
does not need a generator, but can still use a toolchain.
A toolchain can be defined, among the built-ins toolchains, with an attribute:
toolchain = "cmake"
Note
At the moment (Conan 1.26), the only available built-in toolchain is the CMake one.
But in the more general case, and if it needs any specific configuration beyond the default one:
from conans import CMakeToolchain
def toolchain(self):
tc = CMakeToolchain(self)
# customize toolchain "tc"
tc.write_toolchain_files()
It is possible to use the toolchain() method to create your own files, which will typically be
deduced from the current configuration of self.settings and self.options.
from conans import CMakeToolchain
from conans.tools import save
def toolchain(self):
# Based on the self.settings, self.options, the user
# can generate their own files:
save("mytoolchain.tool", "my own toolchain contents, deduced from the settings and options")
# The "mytoolchain.tool" file can be used by the build system to
# define the build
And as usual, you can create your own toolchain helpers, put them in a python_requires package and reuse them in all
your recipes.
Toolchains have some important advantages:
They execute at conan install time. They generate files, not command line arguments, providing better reproducibility and debugging of builds.
They provide a better developer experience. The command line used by developers locally, like
cmake ...will achieve the same build, with the same flags, as the conan build or the build that is done in the cache with a conan create.They are more extensible and configurable.
The toolchains implement most of the build system logic, leaving the build helpers, like CMake(),
doing less work, and acting basically as a high level wrapper of the build system. Many of the
existing arguments, attributes or methds of those build helpers will not be available. Check
the documentation of each toolchain to check the associated build helper available functionality.
from conans import CMakeToolchain, CMake
def toolchain(self):
tc = CMakeToolchain(self)
# customize toolchain "tc"
tc.write_toolchain_files()
def build(self):
# NOTE: This is a simplified helper
# Not all arguments attributes and methods might be available
cmake = CMake(self)