Add infrastructure for generators to select a build tool instance

Add cache entry `CMAKE_GENERATOR_INSTANCE` to hold the instance location
persistently across re-runs of CMake in a given build tree.

For now we reject the option by default if explicitly set.  It will be
implemented on a per-generator basis.  Pass the setting into try_compile
project generation.  Add a RunCMake.GeneratorInstance test to cover
basic use cases for the option.  Verify that `CMAKE_GENERATOR_INSTANCE`
is empty by default, and that it is rejected when the generator does not
support a user setting.

Issue: #17268

3 files changed, 30 insertions, 0 deletions

diff --git a/Help/manual/cmake-variables.7.rst b/Help/manual/cmake-variables.7.rst
index 3880bcf..b37d473 100644
--- a/Help/manual/cmake-variables.7.rst
+++ b/Help/manual/cmake-variables.7.rst
@@ -42,6 +42,7 @@ Variables that Provide Information
    /variable/CMAKE_FIND_PACKAGE_SORT_DIRECTION
    /variable/CMAKE_FIND_PACKAGE_SORT_ORDER
    /variable/CMAKE_GENERATOR
+   /variable/CMAKE_GENERATOR_INSTANCE
    /variable/CMAKE_GENERATOR_PLATFORM
    /variable/CMAKE_GENERATOR_TOOLSET
    /variable/CMAKE_HOME_DIRECTORY
diff --git a/Help/release/dev/generator-instance.rst b/Help/release/dev/generator-instance.rst
new file mode 100644
index 0000000..5e92f7d
--- /dev/null
+++ b/Help/release/dev/generator-instance.rst
@@ -0,0 +1,7 @@
+generator-instance
+------------------
+
+* A :variable:`CMAKE_GENERATOR_INSTANCE` variable was introduced
+  to hold the selected instance of the generator's corresponding
+  native tools if multiple are available.  Currently no generators
+  actually use this, but the infrastructure is in place.
diff --git a/Help/variable/CMAKE_GENERATOR_INSTANCE.rst b/Help/variable/CMAKE_GENERATOR_INSTANCE.rst
new file mode 100644
index 0000000..7c2c280
--- /dev/null
+++ b/Help/variable/CMAKE_GENERATOR_INSTANCE.rst
@@ -0,0 +1,22 @@
+CMAKE_GENERATOR_INSTANCE
+------------------------
+
+Generator-specific instance specification provided by user.
+
+Some CMake generators support selection of an instance of the native build
+system when multiple instances are available.  If the user specifies an
+instance (e.g. by setting this cache entry), or after a default instance is
+chosen when a build tree is first configured, the value will be available in
+this variable.
+
+The value of this variable should never be modified by project code.
+A toolchain file specified by the :variable:`CMAKE_TOOLCHAIN_FILE`
+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:
+
+* None
+
+See native build system documentation for allowed instance values.