Merge topic 'vs-instance'

195d47e213 VS: Allow CMAKE_GENERATOR_INSTANCE to specify portable instance
ec8d37b3b1 VS: Support version specification in CMAKE_GENERATOR_INSTANCE
8e6d930e8c VS: Parse comma-separated fields from CMAKE_GENERATOR_INSTANCE
5d1f377737 cmVSSetupHelper: Factor out helper to load MSVC toolset version
006fe1e919 cmVSSetupHelper: Convert wide to narrow strings early
f5dfc788b8 cmVSSetupHelper: Drop unused InstanceId field
3213e2595d cmVSSetupHelper: Drop unused ullVersion field
152f9978dd Help: De-duplicate VS instance selection documentation

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

5 files changed, 50 insertions, 41 deletions

diff --git a/Help/generator/Visual Studio 15 2017.rst b/Help/generator/Visual Studio 15 2017.rst
index b4d6f6d..912afad 100644
--- a/Help/generator/Visual Studio 15 2017.rst
+++ b/Help/generator/Visual Studio 15 2017.rst
@@ -17,18 +17,8 @@ Instance Selection
 
 .. versionadded:: 3.11
 
-VS 2017 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 ``VS150COMNTOOLS`` 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.
+VS 2017 supports multiple installations on the same machine.  The
+:variable:`CMAKE_GENERATOR_INSTANCE` variable may be used to select one.
 
 Platform Selection
 ^^^^^^^^^^^^^^^^^^
diff --git a/Help/generator/Visual Studio 16 2019.rst b/Help/generator/Visual Studio 16 2019.rst
index 72399e0..6cefe6d 100644
--- a/Help/generator/Visual Studio 16 2019.rst
+++ b/Help/generator/Visual Studio 16 2019.rst
@@ -15,18 +15,8 @@ Powershell, Python, etc.) are not supported.
 Instance Selection
 ^^^^^^^^^^^^^^^^^^
 
-VS 2019 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 ``VS160COMNTOOLS`` 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.
+VS 2019 supports multiple installations on the same machine.  The
+:variable:`CMAKE_GENERATOR_INSTANCE` variable may be used to select one.
 
 Platform Selection
 ^^^^^^^^^^^^^^^^^^
diff --git a/Help/generator/Visual Studio 17 2022.rst b/Help/generator/Visual Studio 17 2022.rst
index b3f49f3..edf9d60 100644
--- a/Help/generator/Visual Studio 17 2022.rst
+++ b/Help/generator/Visual Studio 17 2022.rst
@@ -15,18 +15,8 @@ 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.
+VS 2022 supports multiple installations on the same machine.  The
+:variable:`CMAKE_GENERATOR_INSTANCE` variable may be used to select one.
 
 Platform Selection
 ^^^^^^^^^^^^^^^^^^
diff --git a/Help/release/dev/vs-instance.rst b/Help/release/dev/vs-instance.rst
new file mode 100644
index 0000000..0b9ff4b
--- /dev/null
+++ b/Help/release/dev/vs-instance.rst
@@ -0,0 +1,6 @@
+vs-instance
+-----------
+
+* The :ref:`Visual Studio Generators` for VS 2017 and above learned to
+  use portable instances of Visual Studio not known to the VS installer.
+  See the :variable:`CMAKE_GENERATOR_INSTANCE` variable.
diff --git a/Help/variable/CMAKE_GENERATOR_INSTANCE.rst b/Help/variable/CMAKE_GENERATOR_INSTANCE.rst
index 5858d7a..6a35f17 100644
--- a/Help/variable/CMAKE_GENERATOR_INSTANCE.rst
+++ b/Help/variable/CMAKE_GENERATOR_INSTANCE.rst
@@ -18,10 +18,43 @@ variable may initialize ``CMAKE_GENERATOR_INSTANCE`` as a cache entry.
 Once a given build tree has been initialized with a particular value
 for this variable, changing the value has undefined behavior.
 
-Instance specification is supported only on specific generators:
+Instance specification is supported only on specific generators.
 
-* For the :generator:`Visual Studio 15 2017` generator (and above)
-  this specifies the absolute path to the VS installation directory
-  of the selected VS instance.
+Visual Studio Instance Selection
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-See native build system documentation for allowed instance values.
+:ref:`Visual Studio Generators` support instance specification for
+Visual Studio 2017 and above.  The ``CMAKE_GENERATOR_INSTANCE`` variable
+may be set as a cache entry selecting an instance of Visual Studio
+via one of the following forms:
+
+* ``location``
+* ``location[,key=value]*``
+* ``key=value[,key=value]*``
+
+The ``location`` specifies the absolute path to the top-level directory
+of the VS installation.
+
+The ``key=value`` pairs form a comma-separated list of options to
+specify details of the instance selection.
+Supported pairs are:
+
+``version=<major>.<minor>.<MMMDD>.<BBB>``
+  .. versionadded:: 3.23
+
+  Specify the 4-component VS Build Version.
+
+.. versionadded:: 3.23
+
+  A portable VS instance may be specified that is not known to the
+  Visual Studio Installer tool.  The ``location`` and ``version=``
+  values must both be provided.
+
+If the value of ``CMAKE_GENERATOR_INSTANCE`` 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.  If an environment variable of the form
+``VS##0COMNTOOLS``, where ``##`` the Visual Studio major version number,
+is set and points to the ``Common7/Tools`` directory within one of the
+VS instances, that instance will be used.  Otherwise, if more than one
+VS instance is installed we do not define which one is chosen by default.