Merge topic '17870-iphone-friendly-cmake'

e8ee8cab97 Xcode: Completely disable code signing for compiler id detection
11da882a12 Apple: Introduce separate system name for iOS, tvOS, and watchOS
36cf44a7a3 Tests: Isolate RunCMake.XcodeProject per-device cases from host arch

Acked-by: Kitware Robot <kwrobot@kitware.com>
Merge-request: !2392

2 files changed, 76 insertions, 0 deletions

diff --git a/Help/manual/cmake-toolchains.7.rst b/Help/manual/cmake-toolchains.7.rst
index 8554e87..d214e4a 100644
--- a/Help/manual/cmake-toolchains.7.rst
+++ b/Help/manual/cmake-toolchains.7.rst
@@ -522,3 +522,74 @@ 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.
+By default, CMake avoids the need for code signing during the internal
+configuration phase (i.e compiler ID and feature detection).
+
+.. _`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.
diff --git a/Help/release/dev/iphone-friendly-cmake.rst b/Help/release/dev/iphone-friendly-cmake.rst
new file mode 100644
index 0000000..f32f0d1
--- /dev/null
+++ b/Help/release/dev/iphone-friendly-cmake.rst
@@ -0,0 +1,5 @@
+iphone-friendly-cmake
+---------------------
+
+* CMake now supports :ref:`Cross Compiling for iOS, tvOS, or watchOS`
+  using simple toolchain files.