XcodeDeps¶

The XcodeDeps tool is the dependency information generator for Xcode. It will generate multiple .xcconfig configuration files, the can be used by consumers using xcodebuild or Xcode. To use them just add the generated configuration files to the Xcode project or set the -xcconfig argument from the command line.

The XcodeDeps generator can be used by name in conanfiles:

conanfile.py¶

class Pkg(ConanFile):
    generators = "XcodeDeps"

conanfile.txt¶

[generators]
XcodeDeps

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

conanfile.py¶

from conan import ConanFile
from conan.tools.apple import XcodeDeps

class Pkg(ConanFile):
    settings = "os", "compiler", "arch", "build_type"
    requires = "libpng/1.6.37@" # Note libpng has zlib as transitive dependency

    def generate(self):
        xcode = XcodeDeps(self)
        xcode.generate()

When the XcodeDeps generator is used, every invocation of conan install will generate several configuration files, per dependency and configuration. For the conanfile.py above, for example:

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

This generator is multi-configuration. It will generate different files for the different Debug/Release configurations for each requirement. It will also generate one single file (conandeps.xcconfig) aggregating all the files for the direct dependencies (just libpng in this case). The above commands generate the following files:

.
├── conan_config.xcconfig
├── conan_libpng.xcconfig
├── conan_libpng_libpng.xcconfig
├── conan_libpng_libpng_debug_x86_64.xcconfig
├── conan_libpng_libpng_release_x86_64.xcconfig
├── conan_zlib.xcconfig
├── conan_zlib_zlib.xcconfig
├── conan_zlib_zlib_debug_x86_64.xcconfig
├── conan_zlib_zlib_release_x86_64.xcconfig
└── conandeps.xcconfig

The first conan install with the default Release and x86_64 configuration generates:

conan_libpng_libpng_release_x86_64.xcconfig: declares variables with conditional logic to be considered only for the active configuration in Xcode or the one passed by command line to xcodebuild.
conan_libpng_libpng.xcconfig: includes conan_libpng_libpng_release_x86_64.xcconfig and declares the following Xcode build settings: SYSTEM_HEADER_SEARCH_PATHS, GCC_PREPROCESSOR_DEFINITIONS, OTHER_CFLAGS, OTHER_CPLUSPLUSFLAGS, FRAMEWORK_SEARCH_PATHS, LIBRARY_SEARCH_PATHS, OTHER_LDFLAGS. It also includes the generated xcconfig files for transitive dependencies (conan_zlib_zlib.xcconfig in this case).
conan_libpng.xcconfig: in this case it only includes conan_libpng_libpng.xcconfig, but in the case that the required package has components, this file will include all of the components of the package.
Same 3 files will be generated for each dependency in the graph. In this case, as zlib is a dependency of libpng it will generate: conan_zlib_zlib_release_x86_64.xcconfig, conan_zlib_zlib.xcconfig and conan_zlib.xcconfig.
conandeps.xcconfig: configuration files including all direct dependencies, in this case, it just includes conan_libpng.xcconfig.
The main conan_config.xcconfig file, to be added to the project. Includes both the files from this generator and the generated by the XcodeToolchain in case it was also set.

The second conan install -s build_type=Debug generates:

conan_libpng_libpng_debug_x86_64.xcconfig: same variables as the one below for Debug configuration.
conan_libpng_libpng.xcconfig: this file has been already created by the previous command, now it’s modified to add the include for conan_libpng_debug_x86_64.xcconfig.
conan_libpng.xcconfig: this file will remain the same.
Like in the previous command the same 3 files will be generated for each dependency in the graph. In this case, as zlib is a dependency of libpng it will generate: conan_zlib_zlib_debug_x86_64.xcconfig, conan_zlib_zlib.xcconfig and conan_zlib.xcconfig.
conandeps.xcconfig: configuration files including all direct dependencies, in this case, it just includes conan_libpng.xcconfig.
The main conan_config.xcconfig file, to be added to the project. Includes both the files from this generator and the generated by the XcodeToolchain in case it was also set.

If you want to add this dependencies to you Xcode project, you just have to add the conan_config.xcconfig configuration file for all of the configurations you want to use (usually Debug and Release).

Additional variables defined¶

Besides the variables that define the Xcode build settings mentioned above, there are additional variables declared that may be useful to use in your Xcode project:

PACKAGE_ROOT_<package_name>: Set to the location of the package_folder attribute.

Components support¶

This generator supports packages with components. That means that:

If a dependency package_info() declares cpp_info.requires on some components, the generated .xcconfig files will contain includes to only those components.
The current package requires will be fully dependent on and all components. Recall that the package_info() only applies for consumers, but not to the current package.

Custom configurations¶

If your Xcode project defines custom configurations, like ReleaseShared, or MyCustomConfig, it is possible to define it into the XcodeDeps generator, so different project configurations can use different set of dependencies. Let’s say that our current project can be built as a shared library, with the custom configuration ReleaseShared, and the package also controls this with the shared option:

from conan import ConanFile
from conan.tools.apple import XcodeDeps

class Pkg(ConanFile):
    settings = "os", "compiler", "arch", "build_type"
    options = {"shared": [True, False]}
    default_options = {"shared": False}
    requires = "zlib/1.2.11"

    def generate(self):
        xcode = XcodeDeps(self)
        # We assume that -o *:shared=True is used to install all shared deps too
        if self.options.shared:
            xcode.configuration = str(self.settings.build_type) + "Shared"
        xcode.generate()

This will manage to generate new .xcconfig files for this custom configuration, and when you switch to this configuration in the IDE, the build system will take the correct values depending whether we want to link with shared or static libraries.