.. _conan_tools_apple_xcodetoolchain:

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:

.. code-block:: python
    :caption: conanfile.py

    class Pkg(ConanFile):
        generators = "XcodeToolchain"

.. code-block:: text
    :caption: conanfile.txt

    [generators]
    XcodeToolchain

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

.. code:: python

    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:

.. code-block:: bash

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

Will create these files:

.. code-block:: bash

    .
    ├── 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
  :ref:`XcodeDeps<conan_tools_apple_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`` 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 :ref:`the
  configuration section<xcodetoolchain_conf>` 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:

- ``MACOSX_DEPLOYMENT_TARGET`` is based on the value of the ``os.version`` setting and
  will make the build system to pass the flag ``-mmacosx-version-min`` with that value (if
  set). It defines the operating system version the binary should run into.
- ``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.

.. _xcodetoolchain_conf:

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.