XcodeToolchain

The XcodeToolchain is the toolchain generator for Xcode. It will generate .xcconfig configuration files that can be added to Xcode projects. This generator translates the current package configuration, settings, and options, into Xcode .xcconfig files syntax.

The XcodeToolchain generator can be used by name in conanfiles:

conanfile.py
class Pkg(ConanFile):
    generators = "XcodeToolchain"
conanfile.txt
[generators]
XcodeToolchain

And it can also be fully instantiated in the conanfile generate() method:

from conan import ConanFile
from conan.tools.apple import XcodeToolchain

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

    def generate(self):
        tc = XcodeToolchain(self)
        tc.generate()

The XcodeToolchain will generate three files after a conan install command. As explained above for the XcodeDeps generator, each different configuration will create a set of files with different names. For example, running conan install for Release first and then Debug configuration:

$ conan install conanfile.py # default is Release
$ conan install conanfile.py -s build_type=Debug

Will create these files:

.
├── conan_config.xcconfig
├── conantoolchain_release_x86_64.xcconfig
├── conantoolchain_debug_x86_64.xcconfig
├── conantoolchain.xcconfig
└── conan_global_flags.xcconfig

Those files are:

  • The main conan_config.xcconfig file, to be added to the project. Includes both the files from this generator and the generated by the XcodeDeps in case it was also set.

  • conantoolchain_<debug/release>_x86_64.xcconfig: declares CLANG_CXX_LIBRARY, CLANG_CXX_LANGUAGE_STANDARD and MACOSX_DEPLOYMENT_TARGET (when os is set to Macos) variables with conditional logic depending on the build configuration, architecture and sdk set.

  • conantoolchain.xcconfig: aggregates all the conantoolchain_<config>_<arch>.xcconfig files for the different installed configurations.

  • conan_global_flags.xcconfig: this file will only be generated in case of any configuration variables related to compiler or linker flags are set. Check the configuration section below for more details.

Every invocation to conan install with different configuration will create a new conantoolchain_<config>_<arch>.xcconfig file that is aggregated in the conantoolchain.xcconfig, so you can have different configurations included in your Xcode project.

The XcodeToolchain files can declare the following Xcode build settings based on Conan settings values:

  • *_DEPLOYMENT_TARGET is based on the value of the os + os.version settings and will make the build system pass respective flag (e.g. MACOSX_DEPLOYMENT_TARGET translates to -mmacosx-version-min for macOS) with that value (if set). It defines the minimum operating system version the binary should run on.

  • CLANG_CXX_LANGUAGE_STANDARD is based on the value of the compiler.cppstd setting that sets the C++ language standard.

  • CLANG_CXX_LIBRARY is based on the value of the compiler.libcxx setting and sets the version of the C++ standard library to use.

One of the advantages of using toolchains is that they can help to achieve the exact same build with local development flows, than when the package is created in the cache.

conf

This toolchain is also affected by these [conf] variables:

  • tools.build:cxxflags list of C++ flags.

  • tools.build:cflags list of pure C flags.

  • tools.build:sharedlinkflags list of flags that will be used by the linker when creating a shared library.

  • tools.build:exelinkflags list of flags that will be used by the linker when creating an executable.

  • tools.build:defines list of preprocessor definitions.

If you set any of these variables, the toolchain will use them to generate the conan_global_flags.xcconfig file that will be included from the conan_config.xcconfig file.