Apple: Introduce separate system name for iOS, tvOS, and watchOS

- Remove code signing requirements for non-macOS
- Do not set deployment target for non-macOS
- Build static library for compiler feature detection for non-macOS
- Use framework to run CompilerId tests for watchOS
- Port tests to new SDK handling
- Add new Apple cross-compiling section to toolchain documentation

Closes: #17870

1 files changed, 69 insertions, 0 deletions

diff --git a/Help/manual/cmake-toolchains.7.rst b/Help/manual/cmake-toolchains.7.rst
index 8554e87..565368b 100644
--- a/Help/manual/cmake-toolchains.7.rst
+++ b/Help/manual/cmake-toolchains.7.rst
@@ -522,3 +522,72 @@ See also target properties:
 * :prop_tgt:`ANDROID_SECURE_PROPS_PATH`
 * :prop_tgt:`ANDROID_SKIP_ANT_STEP`
 * :prop_tgt:`ANDROID_STL_TYPE`
+
+.. _`Cross Compiling for iOS, tvOS, or watchOS`:
+
+Cross Compiling for iOS, tvOS, or watchOS
+-----------------------------------------
+
+For cross-compiling to iOS, tvOS, or watchOS, the :generator:`Xcode`
+generator is recommended.  The :generator:`Unix Makefiles` or
+:generator:`Ninja` generators can also be used, but they require the
+project to handle more areas like target CPU selection and code signing.
+
+Any of the three systems can be targetted by setting the
+:variable:`CMAKE_SYSTEM_NAME` variable to a value from the table below.
+By default, the latest Device SDK is chosen.  As for all Apple platforms,
+a different SDK (e.g. a simulator) can be selected by setting the
+:variable:`CMAKE_OSX_SYSROOT` variable, although this should rarely be
+necessary (see :ref:`Switching Between Device and Simulator` below).
+A list of available SDKs can be obtained by running ``xcodebuild -showsdks``.
+
+=======  ================= ==================== ================
+OS       CMAKE_SYSTEM_NAME Device SDK (default) Simulator SDK
+=======  ================= ==================== ================
+iOS      iOS               iphoneos             iphonesimulator
+tvOS     tvOS              appletvos            appletvsimulator
+watchOS  watchOS           watchos              watchsimulator
+=======  ================= ==================== ================
+
+For example, to create a CMake configuration for iOS, the following
+command is sufficient:
+
+.. code-block:: console
+
+  cmake .. -GXcode -DCMAKE_SYSTEM_NAME=iOS
+
+Code Signing
+^^^^^^^^^^^^
+
+Some build artifacts for the embedded Apple platforms require mandatory
+code signing.  If the :generator:`Xcode` generator is being used and
+code signing is required or desired, the developmemt team ID can be
+specified via the ``CMAKE_XCODE_ATTRIBUTE_DEVELOPMENT_TEAM`` CMake variable.
+This team ID will then be included in the generated Xcode project.
+
+.. _`Switching Between Device and Simulator`:
+
+Switching Between Device and Simulator
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+When configuring for any of the embedded platforms, one can target either
+real devices or the simulator.  Both have their own separate SDK, but CMake
+only supports specifying a single SDK for the configuration phase.  This
+means the developer must select one or the other at configuration time.
+When using the :generator:`Xcode` generator, this is less of a limitation
+because Xcode still allows you to build for either a device or a simulator,
+even though configuration was only performed for one of the two.  From
+within the Xcode IDE, builds are performed for the selected "destination"
+platform.  When building from the command line, the desired sdk can be
+specified directly by passing a ``-sdk`` option to the underlying build
+tool (``xcodebuild``).  For example:
+
+.. code-block:: console
+
+  $ cmake --build ... -- -sdk iphonesimulator
+
+Please note that checks made during configuration were performed against
+the configure-time SDK and might not hold true for other SDKs.  Commands
+like :command:`find_package`, :command:`find_library`, etc. store and use
+details only for the configured SDK/platform, so they can be problematic
+if wanting to switch between device and simulator builds.