10 files changed, 95 insertions, 25 deletions
diff --git a/Help/dev/experimental.rst b/Help/dev/experimental.rst
index 9cf33eb..2380de4 100644
--- a/Help/dev/experimental.rst
+++ b/Help/dev/experimental.rst
@@ -39,13 +39,7 @@ to the file specified by the ``<DEP_FILE>`` placeholder, and write module
 dependencies to the file specified by the ``<DYNDEP_FILE>`` placeholder.
 
 The module dependencies should be written in the format described
-by the `P1689r3`_ paper, with the following updates:
-
-* Omit the ``outputs``, ``inputs``, and ``depends`` fields from
-  each entry in the ``rules`` array.  They are unused.
-* Flatten ``future-compile`` members directly into each rule.
-* Factor a ``primary-output`` field out of the now-flattened ``outputs``.
-* The ``work-directory`` field is optional.
+by the `P1689r4`_ paper.
 
 Compiler writers may try out their scanning functionality using
 the `cxx-modules-sandbox`_ test project, modified to set variables
@@ -72,5 +66,5 @@ the GCC documentation, but the relevant section for the purposes of CMake is:
     -- GCC module mapper documentation
 
 .. _`D1483r1`: https://mathstuf.fedorapeople.org/fortran-modules/fortran-modules.html
-.. _`P1689r3`: http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2020/p1689r3.html
+.. _`P1689r4`: http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2021/p1689r4.html
 .. _`cxx-modules-sandbox`: https://github.com/mathstuf/cxx-modules-sandbox
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..204880b 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.
@@ -53,9 +57,9 @@ Command-Line
 * :manual:`cmake(1)` gained the ``--toolchain <path/to/file>``
   command-line option to specify a toolchain file.
 
-* :manual:`cmake(1)` ``-E capabilities`` output now contains for each
-  generator a ``supportedPlatforms`` field listing platforms known to
-  be supported in :variable:`CMAKE_GENERATOR_PLATFORM`.
+* :manual:`cmake(1)` ``-E capabilities`` output, for some generators,
+  may now contain a ``supportedPlatforms`` field listing platforms
+  known to be supported in :variable:`CMAKE_GENERATOR_PLATFORM`.
 
 * Messages printed to a terminal now may be colored by message type.
 
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.