VS: Add Visual Studio 17 2022 generator

Fixes: #22339

4 files changed, 69 insertions, 0 deletions

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.