Clarrify folder layout

[GregDomjan]

In configuring the MacOS XCode build, for some reason I had chosen to set/change the layout to a generic_layout.

I've only just come to understand that this was changing the management of XCodeDeps config forcing the xcconfig generation into different folders so that it was not preparing a multi config a described

docs/reference/tools/apple/xcodedeps.rst

Lines 50 to 53 in 7879318

	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:

Looking at the XCodeDeps doc, it was not clear at this point why the generate one single file (*conandeps.xcconfig*) aggregating all the files for the direct dependencies was not creating the single file instead creating 1 in each build_type and arch.

It may be helpful to others to understand this link between layout and the deps/tools setup

[memsharded]

Hi @GregDomjan

Thanks for your feedback

generic_layout.

Sorry, it is not very clear what do you mean. Did you mean a basic_layout()?

[GregDomjan]

Ah, yes, sorry @memsharded
I think I had tried to set the source folder, which wasn't actually needed yet because we post process with XCode calls rather than running conan build.

            basic_layout(self, src_folder="MacOsService")

Sorry, I don't know why I typed it instead of just copying when raising the issue

[memsharded]

What would be the improvement to the docs then?
Something like a very visible note that says: "beware that the layout definition is build-system dependent and attached to how the specific build scripts expect to find things"? Where exactly in the docs would you expect to see that?

[GregDomjan]

I was having trouble thinking up how to improve, so I asked Claude which gave the guts for these 3 suggestions.
One thing I'm not clear on how to reference is the "default layout" where a layout like cmake or basic is not specifically setup.

1. Clarify "multi-configuration" immediately after it's introduced

Current text (after the file tree):

This generator is multi-configuration. It will generate different files for the different Debug/Release configurations...

Suggested replacement:

This generator is multi-configuration. Unlike single-configuration generators that require separate output directories per build type, XcodeDeps is designed to be invoked multiple times — once per arch/build_type combination — all writing into the same output directory. Each invocation updates the shared intermediate files (e.g. conan_libpng_libpng.xcconfig) to append an #include for the new configuration's arch/build_type-specific file. After all invocations are complete, the intermediate files aggregate all configurations, and a single conan_config.xcconfig can be added to your Xcode project once, covering all build configurations.

---

2. Clarify "one single file" and the aggregation model

Current text:

It will also generate one single file (conandeps.xcconfig) aggregating all the files for the direct dependencies (just libpng in this case).

Suggested replacement:

It will also generate one single file (conandeps.xcconfig) that aggregates all direct dependencies (just libpng in this case). This file is not per-configuration; it only includes the top-level conan_<pkg>.xcconfig files, which are themselves stable across configurations. The per-arch/build_type specifics are handled deeper in the include chain.

---

3. Add a new "Using with layouts" warning section

This is the most important missing piece. Add it after the file tree walkthrough:

.. note:: Using XcodeDeps with a layout (e.g. ``basic_layout``)

   When a :ref:`layout <conan_tools_layout>` is used — for example ``basic_layout()``
   — the generators output folder is set per-configuration::

       build-release/conan/    # conan install -s build_type=Release
       build-debug/conan/      # conan install -s build_type=Debug

   In this case each ``conan install`` writes a **separate, independent** copy of all
   xcconfig files into its own folder. The multi-configuration accumulation described
   above does **not** occur, because the two calls write to different directories.
   You will end up with two separate ``conandeps.xcconfig`` files that cannot be
   combined by simply including both.

   To preserve the multi-configuration behaviour while still using a layout, place the
   generators output in a **shared, fixed directory** that is independent of
   ``build_type``::

       def layout(self):
           basic_layout(self)
           # Override the generators folder to be shared across configurations
           self.folders.generators = "conan"

   This way all ``conan install`` invocations write to the same ``conan/`` folder, the
   intermediate xcconfig files accumulate all configurations as expected, and you add
   ``conan/conan_config.xcconfig`` once to your Xcode project.