From 3e9c5ed85976da3268f2d607bcfc4330e532dae2 Mon Sep 17 00:00:00 2001 From: czoido Date: Wed, 27 Oct 2021 16:41:54 +0200 Subject: [PATCH 1/4] add draft --- reference/conanfile/tools.rst | 1 + reference/conanfile/tools/apple.rst | 102 ++++++++++++++++++++++++++++ 2 files changed, 103 insertions(+) create mode 100644 reference/conanfile/tools/apple.rst diff --git a/reference/conanfile/tools.rst b/reference/conanfile/tools.rst index 361f79af9c2..80d1ea10caa 100644 --- a/reference/conanfile/tools.rst +++ b/reference/conanfile/tools.rst @@ -42,6 +42,7 @@ Contents: tools/cmake tools/gnu tools/google + tools/apple tools/meson tools/intel tools/microsoft diff --git a/reference/conanfile/tools/apple.rst b/reference/conanfile/tools/apple.rst new file mode 100644 index 00000000000..7dc39873946 --- /dev/null +++ b/reference/conanfile/tools/apple.rst @@ -0,0 +1,102 @@ +.. _conan_tools_apple: + +conan.tools.apple +================= + +.. warning:: + + These tools are **experimental** and subject to breaking changes. + + +XcodeDeps +--------- + +Available since: `1.42.0 `_ + +The ``XcodeDeps`` tool is the dependency information generator for *Xcode*. It will generate multiple +*.xcconfig* configuration files, to be used by consumers using *xcodebuild* or *Xcode*, just adding the +generated configuration files to the solution and projects. + +It is important to highlight that this one is a **dependencies generator** and it is focused +on the **dependencies** of a conanfile, not the current build. + +The ``XcodeDeps`` generator can be used by name in conanfiles: + +.. code-block:: python + :caption: conanfile.py + + class Pkg(ConanFile): + generators = "XcodeDeps" + +.. code-block:: text + :caption: conanfile.txt + + [generators] + XcodeDeps + +And it can also be fully instantiated in the conanfile ``generate()`` method: + +.. code-block:: python + :caption: conanfile.py + + from conans import ConanFile + from conan.tools.microsoft 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 per configuration. For the *conanfile.py* +above, for example: + +.. code-block:: bash + + $ conan install conanfile.py # default is Release + $ conan install conanfile.py -s build_type=Debug + +This is a multi-configuration generator, and 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: + +.. code-block:: bash + + . + ├── conan_libpng.xcconfig + ├── conan_libpng_debug_x86_64.xcconfig + ├── conan_libpng_release_x86_64.xcconfig + ├── conan_libpng_vars_debug_x86_64.xcconfig + ├── conan_libpng_vars_release_x86_64.xcconfig + ├── conan_zlib.xcconfig + ├── conan_zlib_debug_x86_64.xcconfig + ├── conan_zlib_release_x86_64.xcconfig + ├── conan_zlib_vars_debug_x86_64.xcconfig + ├── conan_zlib_vars_release_x86_64.xcconfig + └── conandeps.xcconfig + + +The first ``conan install`` with the default *Release* and *x86_64* configuration generates: + +- *conan_libpng_vars_release_x86_64.xcconfig*: declares some intermediate variables that are included in *conan_libpng_release_x86_64.xcconfig* +- *conan_libpng_release_x86_64.xcconfig*: includes *conan_libpng_vars_release_x86_64.xcconfig* and 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.xcconfig*: includes *conan_libpng_release_x86_64.xcconfig* and declares the following *Xcode* build settings: ``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.xcconfig* in this case). +- 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_vars_release_x86_64.xcconfig*, *conan_zlib_release_x86_64.xcconfig* and *conan_zlib.xcconfig*. +- *conandeps.xcconfig*: configuration files including all direct dependencies, in this case, it just includes ``conan_libpng.xcconfig``. + +The second ``conan install -s build_type=Debug`` generates: + +- *conan_libpng_vars_debug_x86_64.xcconfig*: same variables as the one below for *Debug* configuration. +- *conan_libpng_debug_x86_64.xcconfig*: same variables as the one below for *Debug* configuration. +- *conan_libpng.xcconfig*: this file has been already creted by the previous command, now it's modified to add the include for *conan_libpng_debug_x86_64.xcconfig*. +- 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_vars_debug_x86_64.xcconfig*, *conan_zlib_debug_x86_64.xcconfig* and *conan_zlib.xcconfig*. +- *conandeps.xcconfig*: configuration files including all direct dependencies, in this case, it just includes ``conan_libpng.xcconfig``. + +If you want to add this dependencies to you Xcode project, you just have to add the +*conandeps.xcconfig* configuration file for all of the configurations you want to used (usually +*Debug* and *Release*). + From 5fbaad4dc735312e17244a34be7af04b02865452 Mon Sep 17 00:00:00 2001 From: czoido Date: Wed, 27 Oct 2021 18:12:49 +0200 Subject: [PATCH 2/4] minor changes --- reference/conanfile/tools/apple.rst | 14 ++++++-------- 1 file changed, 6 insertions(+), 8 deletions(-) diff --git a/reference/conanfile/tools/apple.rst b/reference/conanfile/tools/apple.rst index 7dc39873946..9ae350aac5c 100644 --- a/reference/conanfile/tools/apple.rst +++ b/reference/conanfile/tools/apple.rst @@ -14,11 +14,9 @@ XcodeDeps Available since: `1.42.0 `_ The ``XcodeDeps`` tool is the dependency information generator for *Xcode*. It will generate multiple -*.xcconfig* configuration files, to be used by consumers using *xcodebuild* or *Xcode*, just adding the -generated configuration files to the solution and projects. - -It is important to highlight that this one is a **dependencies generator** and it is focused -on the **dependencies** of a conanfile, not the current build. +*.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: @@ -51,7 +49,7 @@ And it can also be fully instantiated in the conanfile ``generate()`` method: xcode.generate() When the ``XcodeDeps`` generator is used, every invocation of ``conan install`` will -generate several configuration files, per dependency and per configuration. For the *conanfile.py* +generate several configuration files, per dependency and configuration. For the *conanfile.py* above, for example: .. code-block:: bash @@ -59,7 +57,7 @@ above, for example: $ conan install conanfile.py # default is Release $ conan install conanfile.py -s build_type=Debug -This is a multi-configuration generator, and will generate different files for the different +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: @@ -97,6 +95,6 @@ The second ``conan install -s build_type=Debug`` generates: - *conandeps.xcconfig*: configuration files including all direct dependencies, in this case, it just includes ``conan_libpng.xcconfig``. If you want to add this dependencies to you Xcode project, you just have to add the -*conandeps.xcconfig* configuration file for all of the configurations you want to used (usually +*conandeps.xcconfig* configuration file for all of the configurations you want to use (usually *Debug* and *Release*). From 8af7d91243aa45ba8d8645a920e8ae04f6601e69 Mon Sep 17 00:00:00 2001 From: Carlos Zoido Date: Thu, 28 Oct 2021 09:24:31 +0200 Subject: [PATCH 3/4] Update apple.rst --- reference/conanfile/tools/apple.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/reference/conanfile/tools/apple.rst b/reference/conanfile/tools/apple.rst index 9ae350aac5c..7b109544c57 100644 --- a/reference/conanfile/tools/apple.rst +++ b/reference/conanfile/tools/apple.rst @@ -38,7 +38,7 @@ And it can also be fully instantiated in the conanfile ``generate()`` method: :caption: conanfile.py from conans import ConanFile - from conan.tools.microsoft import XcodeDeps + from conan.tools.apple import XcodeDeps class Pkg(ConanFile): settings = "os", "compiler", "arch", "build_type" From ad03a8c5c25ff79a34db14c30f2f7025d008ec44 Mon Sep 17 00:00:00 2001 From: czoido Date: Thu, 28 Oct 2021 13:46:15 +0200 Subject: [PATCH 4/4] add note about configurations --- reference/conanfile/tools/apple.rst | 32 ++++++++++++++++++++++++++++- 1 file changed, 31 insertions(+), 1 deletion(-) diff --git a/reference/conanfile/tools/apple.rst b/reference/conanfile/tools/apple.rst index 9ae350aac5c..112948ec161 100644 --- a/reference/conanfile/tools/apple.rst +++ b/reference/conanfile/tools/apple.rst @@ -38,7 +38,7 @@ And it can also be fully instantiated in the conanfile ``generate()`` method: :caption: conanfile.py from conans import ConanFile - from conan.tools.microsoft import XcodeDeps + from conan.tools.apple import XcodeDeps class Pkg(ConanFile): settings = "os", "compiler", "arch", "build_type" @@ -98,3 +98,33 @@ If you want to add this dependencies to you Xcode project, you just have to add *conandeps.xcconfig* configuration file for all of the configurations you want to use (usually *Debug* and *Release*). +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: + +.. code-block:: python + + from conans 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 wether we +want to link with shared or static libraries. \ No newline at end of file