Merge topic 'xcode-12-new-build-system'

b8ecd4df5f ExternalProject: Use CMP0114 NEW behavior with Xcode "new build system"
fe258f6382 Tests: Skip RunCMake.XcodeProject device cases for Xcode "new build system"
1c3d2d0951 Tests: Skip Qt*Autogen.MocSkipSource case for Xcode "new build system"
542884e527 Tests: Update RunCMake.XcodeProject cases for Xcode "new build system"
832a78be2d Tests: Update BuildDepends test for Xcode "new build system"
ff76c51ec3 Tests: Update RunCMake.file case with workaround for Xcode "new build system"
1806cdd17c Tests: Avoid duplicate custom commands for Xcode "new build system"
8d5f4c4db9 Xcode: Switch to the "new build system" for Xcode 12 and above
...

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

4 files changed, 55 insertions, 3 deletions

diff --git a/Help/generator/Xcode.rst b/Help/generator/Xcode.rst
index d893ac5..be03a22 100644
--- a/Help/generator/Xcode.rst
+++ b/Help/generator/Xcode.rst
@@ -5,9 +5,31 @@ Generate Xcode project files.
 
 This supports Xcode 5.0 and above.
 
-Toolset Selection
-^^^^^^^^^^^^^^^^^
+.. _`Xcode Build System Selection`:
+
+Toolset and Build System Selection
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 By default Xcode is allowed to select its own default toolchain.
 The :variable:`CMAKE_GENERATOR_TOOLSET` option may be set, perhaps
 via the :manual:`cmake(1)` ``-T`` option, to specify another toolset.
+
+This generator supports toolset specification using one of these forms:
+
+* ``toolset``
+* ``toolset[,key=value]*``
+* ``key=value[,key=value]*``
+
+The ``toolset`` specifies the toolset name.  The selected toolset name
+is provided in the :variable:`CMAKE_XCODE_PLATFORM_TOOLSET` variable.
+
+The ``key=value`` pairs form a comma-separated list of options to
+specify generator-specific details of the toolset selection.
+Supported pairs are:
+
+``buildsystem=<variant>``
+  Specify the buildsystem variant to use.
+  See the :variable:`CMAKE_XCODE_BUILD_SYSTEM` variable for allowed values.
+
+  For example, to select the original build system under Xcode 12,
+  run :manual:`cmake(1)` with the option ``-T buildsystem=1``.
diff --git a/Help/manual/cmake-variables.7.rst b/Help/manual/cmake-variables.7.rst
index d50005c..17d0882 100644
--- a/Help/manual/cmake-variables.7.rst
+++ b/Help/manual/cmake-variables.7.rst
@@ -125,7 +125,7 @@ Variables that Provide Information
    /variable/CMAKE_VS_PLATFORM_TOOLSET_VERSION
    /variable/CMAKE_VS_WINDOWS_TARGET_PLATFORM_VERSION
    /variable/CMAKE_VS_WINDOWS_TARGET_PLATFORM_VERSION_MAXIMUM
-   /variable/CMAKE_XCODE_GENERATE_SCHEME
+   /variable/CMAKE_XCODE_BUILD_SYSTEM
    /variable/CMAKE_XCODE_PLATFORM_TOOLSET
    /variable/PROJECT-NAME_BINARY_DIR
    /variable/PROJECT-NAME_DESCRIPTION
@@ -246,6 +246,7 @@ Variables that Change Behavior
    /variable/CMAKE_USER_MAKE_RULES_OVERRIDE
    /variable/CMAKE_WARN_DEPRECATED
    /variable/CMAKE_WARN_ON_ABSOLUTE_INSTALL_DESTINATION
+   /variable/CMAKE_XCODE_GENERATE_SCHEME
    /variable/CMAKE_XCODE_GENERATE_TOP_LEVEL_PROJECT_ONLY
    /variable/CMAKE_XCODE_LINK_BUILD_PHASE_MODE
    /variable/CMAKE_XCODE_SCHEME_ADDRESS_SANITIZER
diff --git a/Help/release/dev/xcode-12-new-build-system.rst b/Help/release/dev/xcode-12-new-build-system.rst
new file mode 100644
index 0000000..7a497b0
--- /dev/null
+++ b/Help/release/dev/xcode-12-new-build-system.rst
@@ -0,0 +1,7 @@
+xcode-12-new-build-system
+-------------------------
+
+* The :generator:`Xcode` generator now uses the Xcode "new build system"
+  when generating for Xcode 12.0 or higher.
+  See the :variable:`CMAKE_XCODE_BUILD_SYSTEM` variable.
+  One may use ``-T buildsystem=1`` to switch to the legacy build system.
diff --git a/Help/variable/CMAKE_XCODE_BUILD_SYSTEM.rst b/Help/variable/CMAKE_XCODE_BUILD_SYSTEM.rst
new file mode 100644
index 0000000..587a5c9
--- /dev/null
+++ b/Help/variable/CMAKE_XCODE_BUILD_SYSTEM.rst
@@ -0,0 +1,22 @@
+CMAKE_XCODE_BUILD_SYSTEM
+------------------------
+
+Xcode build system selection.
+
+The :generator:`Xcode` generator defines this variable to indicate which
+variant of the Xcode build system will be used.  The value is the
+version of Xcode in which the corresponding build system first became
+mature enough for use by CMake.  The possible values are:
+
+``1``
+  The original Xcode build system.
+  This is the default when using Xcode 11.x or below.
+
+``12``
+  The Xcode "new build system" introduced by Xcode 10.
+  It became mature enough for use by CMake in Xcode 12.
+  This is the default when using Xcode 12.x or above.
+
+The ``CMAKE_XCODE_BUILD_SYSTEM`` variable is informational and should not
+be modified by project code.  See the :ref:`Xcode Build System Selection`
+documentation section to select the Xcode build system.