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

1 files changed, 27 insertions, 0 deletions

diff --git a/Source/cmake.cxx b/Source/cmake.cxx
index d7ed772..cd714c6 100644
--- a/Source/cmake.cxx
+++ b/Source/cmake.cxx
@@ -1326,6 +1326,25 @@ int cmake::ActualConfigure()
                         cmStateEnums::INTERNAL);
   }
 
+  if (const char* instance =
+        this->State->GetInitializedCacheValue("CMAKE_GENERATOR_INSTANCE")) {
+    if (!this->GeneratorInstance.empty() &&
+        this->GeneratorInstance != instance) {
+      std::string message = "Error: generator instance: ";
+      message += this->GeneratorInstance;
+      message += "\nDoes not match the instance used previously: ";
+      message += instance;
+      message += "\nEither remove the CMakeCache.txt file and CMakeFiles "
+                 "directory or choose a different binary directory.";
+      cmSystemTools::Error(message.c_str());
+      return -2;
+    }
+  } else {
+    this->AddCacheEntry(
+      "CMAKE_GENERATOR_INSTANCE", this->GeneratorInstance.c_str(),
+      "Generator instance identifier.", cmStateEnums::INTERNAL);
+  }
+
   if (const char* platformName =
         this->State->GetInitializedCacheValue("CMAKE_GENERATOR_PLATFORM")) {
     if (!this->GeneratorPlatform.empty() &&
@@ -2360,6 +2379,14 @@ int cmake::Build(const std::string& dir, const std::string& target,
               << "\"\n";
     return 1;
   }
+  const char* cachedGeneratorInstance =
+    this->State->GetCacheEntryValue("CMAKE_GENERATOR_INSTANCE");
+  if (cachedGeneratorInstance) {
+    cmMakefile mf(gen.get(), this->GetCurrentSnapshot());
+    if (!gen->SetGeneratorInstance(cachedGeneratorInstance, &mf)) {
+      return 1;
+    }
+  }
   std::string output;
   std::string projName;
   const char* cachedProjectName =