Xcode: Control emission of EFFECTIVE_PLATFORM_NAME

When building with multiple SDKs within one project Xcode requires
the usage of ${EFFECTIVE_PLATFORM_NAME} to put temporary and build
outout into separate directories. For example an iOS device and
simulator build use two different SDKs (iphoneos and iphonesimulator).

In the past cmake tries to detect embedded toolchains that could
possibly use simulators and emitted EFFECTIVE_PLATFORM_NAME (EPN)
at the proper locations. In #16253 Mark noticed that if he
uses macosx and iphoneos in combination the necessary EPN is not
emitted. This is because CMake by default assumes macosx SDK which
does not trigger EPN emission.

The fist naive approach - enabling EPN unconditionally revealed that
then the EPN leaks into generator expressions like $<TARGET_FILE:xxx>
which might be a regression and thus is unacceptable.

The next approach was to add an CMake property to enable EPN emission
unconditionally. This solved the reported problem.

But the EPN leakage also happened for the embedded toolchains already
without anyone noticing. So the control property was turned into a
tri-state one:

 * No definition: EPN is activated for embedded toolchains like before
 * ON: EPN is always emitted
 * OFF: EPN is never emitted

That approach gives the user the chance to disable EPN for embedded
toolchains and restores generator expression functionality for those.

Closes: #16253

1 files changed, 24 insertions, 0 deletions

diff --git a/Help/prop_gbl/XCODE_EMIT_EFFECTIVE_PLATFORM_NAME.rst b/Help/prop_gbl/XCODE_EMIT_EFFECTIVE_PLATFORM_NAME.rst
new file mode 100644
index 0000000..9a6086e
--- /dev/null
+++ b/Help/prop_gbl/XCODE_EMIT_EFFECTIVE_PLATFORM_NAME.rst
@@ -0,0 +1,24 @@
+XCODE_EMIT_EFFECTIVE_PLATFORM_NAME
+----------------------------------
+
+Control emission of ``EFFECTIVE_PLATFORM_NAME`` by the Xcode generator.
+
+It is required for building the same target with multiple SDKs. A
+common use case is the parallel use of ``iphoneos`` and
+``iphonesimulator`` SDKs.
+
+Three different states possible that control when the Xcode generator
+emits the ``EFFECTIVE_PLATFORM_NAME`` variable:
+
+- If set to ``ON`` it will always be emitted
+- If set to ``OFF`` it will never be emitted
+- If unset (the default) it will only be emitted when the project was
+  configured for an embedded Xcode SDK like iOS, tvOS, watchOS or any
+  of the simulators.
+
+.. note::
+
+  When this behavior is enable for generated Xcode projects, the
+  ``EFFECTIVE_PLATFORM_NAME`` variable will leak into
+  :manual:`Generator expressions <cmake-generator-expressions(7)>`
+  like ``TARGET_FILE`` and will render those mostly unusable.