Merge topic 'vs2022' into release-3.21

93c718791e VS: Use 64-bit MSBuild in VS 2022
c46b265839 VS: Add Visual Studio 17 2022 generator
b610b7a35c VS: Update v142 CL flag table for VS 17.0 Preview 1
43375c6418 Help: Remove unnecessary Sphinx versionadded markup in VS toolset selection

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

9 files changed, 90 insertions, 14 deletions

diff --git a/Help/generator/VS_TOOLSET_HOST_ARCH.txt b/Help/generator/VS_TOOLSET_HOST_ARCH.txt
index 069638b..0293631 100644
--- a/Help/generator/VS_TOOLSET_HOST_ARCH.txt
+++ b/Help/generator/VS_TOOLSET_HOST_ARCH.txt
@@ -1,11 +1,7 @@
-.. versionadded:: 3.8
-  For each toolset that comes with this version of Visual Studio, there are
-  variants that are themselves compiled for 32-bit (``x86``) and
-  64-bit (``x64``) hosts (independent of the architecture they target).
-  |VS_TOOLSET_HOST_ARCH_DEFAULT|
-  One may explicitly request use of either the 32-bit or 64-bit host tools
-  by adding either ``host=x86`` or ``host=x64`` to the toolset specification.
-  See the :variable:`CMAKE_GENERATOR_TOOLSET` variable for details.
-
-.. versionadded:: 3.14
-  Added support for ``host=x86`` option.
+For each toolset that comes with this version of Visual Studio, there are
+variants that are themselves compiled for 32-bit (``x86``) and
+64-bit (``x64``) hosts (independent of the architecture they target).
+|VS_TOOLSET_HOST_ARCH_DEFAULT|
+One may explicitly request use of either the 32-bit or 64-bit host tools
+by adding either ``host=x86`` or ``host=x64`` to the toolset specification.
+See the :variable:`CMAKE_GENERATOR_TOOLSET` variable for details.
diff --git a/Help/generator/VS_TOOLSET_HOST_ARCH_LEGACY.txt b/Help/generator/VS_TOOLSET_HOST_ARCH_LEGACY.txt
new file mode 100644
index 0000000..069638b
--- /dev/null
+++ b/Help/generator/VS_TOOLSET_HOST_ARCH_LEGACY.txt
@@ -0,0 +1,11 @@
+.. versionadded:: 3.8
+  For each toolset that comes with this version of Visual Studio, there are
+  variants that are themselves compiled for 32-bit (``x86``) and
+  64-bit (``x64``) hosts (independent of the architecture they target).
+  |VS_TOOLSET_HOST_ARCH_DEFAULT|
+  One may explicitly request use of either the 32-bit or 64-bit host tools
+  by adding either ``host=x86`` or ``host=x64`` to the toolset specification.
+  See the :variable:`CMAKE_GENERATOR_TOOLSET` variable for details.
+
+.. versionadded:: 3.14
+  Added support for ``host=x86`` option.
diff --git a/Help/generator/Visual Studio 12 2013.rst b/Help/generator/Visual Studio 12 2013.rst
index b5fa1bf..3b4b1f2 100644
--- a/Help/generator/Visual Studio 12 2013.rst
+++ b/Help/generator/Visual Studio 12 2013.rst
@@ -46,4 +46,4 @@ via the :manual:`cmake(1)` ``-T`` option, to specify another toolset.
 .. |VS_TOOLSET_HOST_ARCH_DEFAULT| replace::
    By default this generator uses the 32-bit variant even on a 64-bit host.
 
-.. include:: VS_TOOLSET_HOST_ARCH.txt
+.. include:: VS_TOOLSET_HOST_ARCH_LEGACY.txt
diff --git a/Help/generator/Visual Studio 14 2015.rst b/Help/generator/Visual Studio 14 2015.rst
index 9c61641..8257723 100644
--- a/Help/generator/Visual Studio 14 2015.rst
+++ b/Help/generator/Visual Studio 14 2015.rst
@@ -44,7 +44,7 @@ via the :manual:`cmake(1)` ``-T`` option, to specify another toolset.
 .. |VS_TOOLSET_HOST_ARCH_DEFAULT| replace::
    By default this generator uses the 32-bit variant even on a 64-bit host.
 
-.. include:: VS_TOOLSET_HOST_ARCH.txt
+.. include:: VS_TOOLSET_HOST_ARCH_LEGACY.txt
 
 .. _`Windows 10 SDK Maximum Version for VS 2015`:
 
diff --git a/Help/generator/Visual Studio 15 2017.rst b/Help/generator/Visual Studio 15 2017.rst
index a002f2f..a80c57d 100644
--- a/Help/generator/Visual Studio 15 2017.rst
+++ b/Help/generator/Visual Studio 15 2017.rst
@@ -63,4 +63,4 @@ via the :manual:`cmake(1)` ``-T`` option, to specify another toolset.
 .. |VS_TOOLSET_HOST_ARCH_DEFAULT| replace::
    By default this generator uses the 32-bit variant even on a 64-bit host.
 
-.. include:: VS_TOOLSET_HOST_ARCH.txt
+.. include:: VS_TOOLSET_HOST_ARCH_LEGACY.txt
diff --git a/Help/generator/Visual Studio 17 2022.rst b/Help/generator/Visual Studio 17 2022.rst
new file mode 100644
index 0000000..c53f8b7
--- /dev/null
+++ b/Help/generator/Visual Studio 17 2022.rst
@@ -0,0 +1,61 @@
+Visual Studio 17 2022
+---------------------
+
+.. versionadded:: 3.21
+
+Generates Visual Studio 17 (VS 2022) project files.
+
+.. warning::
+
+  This is experimental and based on "Visual Studio 2022 Preview 1.1".
+  As of this version of CMake, VS 2022 has not been released.
+
+Project Types
+^^^^^^^^^^^^^
+
+Only Visual C++ and C# projects may be generated.  Other types of
+projects (JavaScript, Powershell, Python, etc.) are not supported.
+
+Instance Selection
+^^^^^^^^^^^^^^^^^^
+
+VS 2022 supports multiple installations on the same machine.
+The :variable:`CMAKE_GENERATOR_INSTANCE` variable may be set as a
+cache entry containing the absolute path to a Visual Studio instance.
+If the value is not specified explicitly by the user or a toolchain file,
+CMake queries the Visual Studio Installer to locate VS instances, chooses
+one, and sets the variable as a cache entry to hold the value persistently.
+
+When CMake first chooses an instance, if the ``VS170COMNTOOLS`` environment
+variable is set and points to the ``Common7/Tools`` directory within
+one of the instances, that instance will be used.  Otherwise, if more
+than one instance is installed we do not define which one is chosen
+by default.
+
+Platform Selection
+^^^^^^^^^^^^^^^^^^
+
+The default target platform name (architecture) is that of the host
+and is provided in the :variable:`CMAKE_VS_PLATFORM_NAME_DEFAULT` variable.
+
+The :variable:`CMAKE_GENERATOR_PLATFORM` variable may be set, perhaps
+via the :manual:`cmake(1)` ``-A`` option, to specify a target platform
+name (architecture).  For example:
+
+* ``cmake -G "Visual Studio 17 2022" -A Win32``
+* ``cmake -G "Visual Studio 17 2022" -A x64``
+* ``cmake -G "Visual Studio 17 2022" -A ARM``
+* ``cmake -G "Visual Studio 17 2022" -A ARM64``
+
+Toolset Selection
+^^^^^^^^^^^^^^^^^
+
+The ``v142`` toolset that comes with VS 17 2022 Preview 1.1 is selected by
+default.  The :variable:`CMAKE_GENERATOR_TOOLSET` option may be set, perhaps
+via the :manual:`cmake(1)` ``-T`` option, to specify another toolset.
+
+.. |VS_TOOLSET_HOST_ARCH_DEFAULT| replace::
+   By default this generator uses the 64-bit variant on x64 hosts and
+   the 32-bit variant otherwise.
+
+.. include:: VS_TOOLSET_HOST_ARCH.txt
diff --git a/Help/manual/cmake-generators.7.rst b/Help/manual/cmake-generators.7.rst
index 8ca2bf6..663b18d 100644
--- a/Help/manual/cmake-generators.7.rst
+++ b/Help/manual/cmake-generators.7.rst
@@ -91,6 +91,7 @@ Visual Studio Generators
    /generator/Visual Studio 14 2015
    /generator/Visual Studio 15 2017
    /generator/Visual Studio 16 2019
+   /generator/Visual Studio 17 2022
 
 Other Generators
 ^^^^^^^^^^^^^^^^
diff --git a/Help/release/3.21.rst b/Help/release/3.21.rst
index 04354db..1f7a4a1 100644
--- a/Help/release/3.21.rst
+++ b/Help/release/3.21.rst
@@ -26,6 +26,10 @@ Presets
 Generators
 ----------
 
+* The :generator:`Visual Studio 17 2022` generator was added.  This is
+  experimental and based on "Visual Studio 2022 Preview 1.1" because this
+  version of VS has not been released.
+
 * The :ref:`Makefile Generators` and the :generator:`Ninja` generator
   learned to add linker launcher tools along with the linker for ``C``,
   ``CXX``, ``OBJC``, and ``OBJCXX`` languages.
diff --git a/Help/variable/MSVC_VERSION.rst b/Help/variable/MSVC_VERSION.rst
index 45df37f..241eb03 100644
--- a/Help/variable/MSVC_VERSION.rst
+++ b/Help/variable/MSVC_VERSION.rst
@@ -20,5 +20,8 @@ Known version numbers are::
   1910-1919 = VS 15.0 (v141 toolset)
   1920-1929 = VS 16.0 (v142 toolset)
 
+..
+  1930-1939 = VS 17.0 (v143 toolset)
+
 See also the  :variable:`CMAKE_<LANG>_COMPILER_VERSION` and
 :variable:`MSVC_TOOLSET_VERSION` variable.