Merge topic 'generator-instance'

9ffb3538 VS: Select and save a VS 2017 instance persistently
17edfa41 cmVSSetupHelper: Add option to specify an instance
a19b8113 CheckLanguage: Pass generator instance into check
6b3cd64d ExternalProject: Propagate the generator instance
314613d1 Add infrastructure for generators to select a build tool instance

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

38 files changed, 330 insertions, 18 deletions

diff --git a/Help/generator/Visual Studio 15 2017.rst b/Help/generator/Visual Studio 15 2017.rst
index 2ac0449..2cf1aa0 100644
--- a/Help/generator/Visual Studio 15 2017.rst
+++ b/Help/generator/Visual Studio 15 2017.rst
@@ -19,13 +19,17 @@ Instance Selection
 ^^^^^^^^^^^^^^^^^^
 
 VS 2017 supports multiple installations on the same machine.
-CMake queries the Visual Studio Installer to locate VS instances.
-If more than one instance is installed we do not define which one
-is chosen by default.  If the ``VS150COMNTOOLS`` environment variable
-is set and points to the ``Common7/Tools`` directory within one of
-the instances, that instance will be used.  The environment variable
-must remain consistently set whenever CMake is re-run within a given
-build tree.
+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.
 
 Toolset Selection
 ^^^^^^^^^^^^^^^^^
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..a3ff658
--- /dev/null
+++ b/Help/release/dev/generator-instance.rst
@@ -0,0 +1,8 @@
+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.  This is used by the
+  :generator:`Visual Studio 15 2017` generator to hold the
+  selected instance of Visual Studio persistently.
diff --git a/Help/variable/CMAKE_GENERATOR_INSTANCE.rst b/Help/variable/CMAKE_GENERATOR_INSTANCE.rst
new file mode 100644
index 0000000..78c81b1
--- /dev/null
+++ b/Help/variable/CMAKE_GENERATOR_INSTANCE.rst
@@ -0,0 +1,24 @@
+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:
+
+* 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.
+
+See native build system documentation for allowed instance values.
diff --git a/Modules/CheckLanguage.cmake b/Modules/CheckLanguage.cmake
index 1ea91d2..70c14d7 100644
--- a/Modules/CheckLanguage.cmake
+++ b/Modules/CheckLanguage.cmake
@@ -43,11 +43,17 @@ file(WRITE \"\${CMAKE_CURRENT_BINARY_DIR}/result.cmake\"
   \"set(CMAKE_${lang}_COMPILER \\\"\${CMAKE_${lang}_COMPILER}\\\")\\n\"
   )
 ")
+    if(CMAKE_GENERATOR_INSTANCE)
+      set(_D_CMAKE_GENERATOR_INSTANCE "-DCMAKE_GENERATOR_INSTANCE:INTERNAL=${CMAKE_GENERATOR_INSTANCE}")
+    else()
+      set(_D_CMAKE_GENERATOR_INSTANCE "")
+    endif()
     execute_process(
       WORKING_DIRECTORY ${CMAKE_CURRENT_BINARY_DIR}/CMakeFiles/Check${lang}
       COMMAND ${CMAKE_COMMAND} . -G ${CMAKE_GENERATOR}
                                  -A "${CMAKE_GENERATOR_PLATFORM}"
                                  -T "${CMAKE_GENERATOR_TOOLSET}"
+                                 ${_D_CMAKE_GENERATOR_INSTANCE}
       OUTPUT_VARIABLE output
       ERROR_VARIABLE output
       RESULT_VARIABLE result
diff --git a/Modules/ExternalProject.cmake b/Modules/ExternalProject.cmake
index 5897e74..67aac4f 100644
--- a/Modules/ExternalProject.cmake
+++ b/Modules/ExternalProject.cmake
@@ -381,6 +381,11 @@ External Project Definition
       :variable:`CMAKE_GENERATOR_TOOLSET`). It is an error to provide this
       option without the ``CMAKE_GENERATOR`` option.
 
+    ``CMAKE_GENERATOR_INSTANCE <instance>``
+      Pass a generator-specific instance selection to the CMake command (see
+      :variable:`CMAKE_GENERATOR_INSTANCE`). It is an error to provide this
+      option without the ``CMAKE_GENERATOR`` option.
+
     ``CMAKE_ARGS <arg>...``
       The specified arguments are passed to the ``cmake`` command line. They
       can be any argument the ``cmake`` command understands, not just cache
@@ -2754,6 +2759,7 @@ function(_ep_extract_configure_command var name)
     endif()
 
     get_target_property(cmake_generator ${name} _EP_CMAKE_GENERATOR)
+    get_target_property(cmake_generator_instance ${name} _EP_CMAKE_GENERATOR_INSTANCE)
     get_target_property(cmake_generator_platform ${name} _EP_CMAKE_GENERATOR_PLATFORM)
     get_target_property(cmake_generator_toolset ${name} _EP_CMAKE_GENERATOR_TOOLSET)
     if(cmake_generator)
@@ -2764,6 +2770,9 @@ function(_ep_extract_configure_command var name)
       if(cmake_generator_toolset)
         list(APPEND cmd "-T${cmake_generator_toolset}")
       endif()
+      if(cmake_generator_instance)
+        list(APPEND cmd "-DCMAKE_GENERATOR_INSTANCE:INTERNAL=${cmake_generator_instance}")
+      endif()
     else()
       if(CMAKE_EXTRA_GENERATOR)
         list(APPEND cmd "-G${CMAKE_EXTRA_GENERATOR} - ${CMAKE_GENERATOR}")
@@ -2782,6 +2791,12 @@ function(_ep_extract_configure_command var name)
       if(CMAKE_GENERATOR_TOOLSET)
         list(APPEND cmd "-T${CMAKE_GENERATOR_TOOLSET}")
       endif()
+      if(cmake_generator_instance)
+        message(FATAL_ERROR "Option CMAKE_GENERATOR_INSTANCE not allowed without CMAKE_GENERATOR.")
+      endif()
+      if(CMAKE_GENERATOR_INSTANCE)
+        list(APPEND cmd "-DCMAKE_GENERATOR_INSTANCE:INTERNAL=${CMAKE_GENERATOR_INSTANCE}")
+      endif()
     endif()
 
     list(APPEND cmd "<SOURCE_DIR><SOURCE_SUBDIR>")
diff --git a/Source/cmCMakeHostSystemInformationCommand.cxx b/Source/cmCMakeHostSystemInformationCommand.cxx
index 5106f52..662dd74 100644
--- a/Source/cmCMakeHostSystemInformationCommand.cxx
+++ b/Source/cmCMakeHostSystemInformationCommand.cxx
@@ -8,6 +8,9 @@
 #include "cmsys/SystemInformation.hxx"
 
 #if defined(_WIN32)
+#include "cmAlgorithms.h"
+#include "cmGlobalGenerator.h"
+#include "cmGlobalVisualStudio15Generator.h"
 #include "cmSystemTools.h"
 #include "cmVSSetupHelper.h"
 #define HAVE_VS_SETUP_HELPER
@@ -127,6 +130,17 @@ bool cmCMakeHostSystemInformationCommand::GetValue(
     value = this->ValueToString(info.GetOSPlatform());
 #ifdef HAVE_VS_SETUP_HELPER
   } else if (key == "VS_15_DIR") {
+    // If generating for the VS 15 IDE, use the same instance.
+    cmGlobalGenerator* gg = this->Makefile->GetGlobalGenerator();
+    if (cmHasLiteralPrefix(gg->GetName(), "Visual Studio 15 ")) {
+      cmGlobalVisualStudio15Generator* vs15gen =
+        static_cast<cmGlobalVisualStudio15Generator*>(gg);
+      if (vs15gen->GetVSInstance(value)) {
+        return true;
+      }
+    }
+
+    // Otherwise, find a VS 15 instance ourselves.
     cmVSSetupAPIHelper vsSetupAPIHelper;
     if (vsSetupAPIHelper.GetVSInstanceInfo(value)) {
       cmSystemTools::ConvertToUnixSlashes(value);
diff --git a/Source/cmGlobalGenerator.cxx b/Source/cmGlobalGenerator.cxx
index 38669c9..e6d389e 100644
--- a/Source/cmGlobalGenerator.cxx
+++ b/Source/cmGlobalGenerator.cxx
@@ -111,6 +111,26 @@ cmGlobalGenerator::~cmGlobalGenerator()
   delete this->ExtraGenerator;
 }
 
+bool cmGlobalGenerator::SetGeneratorInstance(std::string const& i,
+                                             cmMakefile* mf)
+{
+  if (i.empty()) {
+    return true;
+  }
+
+  std::ostringstream e;
+  /* clang-format off */
+  e <<
+    "Generator\n"
+    "  " << this->GetName() << "\n"
+    "does not support instance specification, but instance\n"
+    "  " << i << "\n"
+    "was specified.";
+  /* clang-format on */
+  mf->IssueMessage(cmake::FATAL_ERROR, e.str());
+  return false;
+}
+
 bool cmGlobalGenerator::SetGeneratorPlatform(std::string const& p,
                                              cmMakefile* mf)
 {
@@ -491,6 +511,13 @@ void cmGlobalGenerator::EnableLanguage(
   }
 
   if (readCMakeSystem) {
+    // Tell the generator about the instance, if any.
+    std::string instance = mf->GetSafeDefinition("CMAKE_GENERATOR_INSTANCE");
+    if (!this->SetGeneratorInstance(instance, mf)) {
+      cmSystemTools::SetFatalErrorOccured();
+      return;
+    }
+
     // Find the native build tool for this generator.
     if (!this->FindMakeProgram(mf)) {
       return;
diff --git a/Source/cmGlobalGenerator.h b/Source/cmGlobalGenerator.h
index 04e9dc1..abbc001 100644
--- a/Source/cmGlobalGenerator.h
+++ b/Source/cmGlobalGenerator.h
@@ -70,6 +70,9 @@ public:
   /** Tell the generator about the target system.  */
   virtual bool SetSystemName(std::string const&, cmMakefile*) { return true; }
 
+  /** Set the generator-specific instance.  Returns true if supported.  */
+  virtual bool SetGeneratorInstance(std::string const& i, cmMakefile* mf);
+
   /** Set the generator-specific platform name.  Returns true if platform
       is supported and false otherwise.  */
   virtual bool SetGeneratorPlatform(std::string const& p, cmMakefile* mf);
diff --git a/Source/cmGlobalVisualStudio15Generator.cxx b/Source/cmGlobalVisualStudio15Generator.cxx
index d2bf7cc..014d93d 100644
--- a/Source/cmGlobalVisualStudio15Generator.cxx
+++ b/Source/cmGlobalVisualStudio15Generator.cxx
@@ -111,6 +111,53 @@ void cmGlobalVisualStudio15Generator::WriteSLNHeader(std::ostream& fout)
   }
 }
 
+bool cmGlobalVisualStudio15Generator::SetGeneratorInstance(
+  std::string const& i, cmMakefile* mf)
+{
+  if (!i.empty()) {
+    if (!this->vsSetupAPIHelper.SetVSInstance(i)) {
+      std::ostringstream e;
+      /* clang-format off */
+      e <<
+        "Generator\n"
+        "  " << this->GetName() << "\n"
+        "could not find specified instance of Visual Studio:\n"
+        "  " << i;
+      /* clang-format on */
+      mf->IssueMessage(cmake::FATAL_ERROR, e.str());
+      return false;
+    }
+  }
+
+  std::string vsInstance;
+  if (!this->vsSetupAPIHelper.GetVSInstanceInfo(vsInstance)) {
+    std::ostringstream e;
+    /* clang-format off */
+    e <<
+      "Generator\n"
+      "  " << this->GetName() << "\n"
+      "could not find any instance of Visual Studio.\n";
+    /* clang-format on */
+    mf->IssueMessage(cmake::FATAL_ERROR, e.str());
+    return false;
+  }
+
+  // Save the selected instance persistently.
+  std::string genInstance = mf->GetSafeDefinition("CMAKE_GENERATOR_INSTANCE");
+  if (vsInstance != genInstance) {
+    this->CMakeInstance->AddCacheEntry(
+      "CMAKE_GENERATOR_INSTANCE", vsInstance.c_str(),
+      "Generator instance identifier.", cmStateEnums::INTERNAL);
+  }
+
+  return true;
+}
+
+bool cmGlobalVisualStudio15Generator::GetVSInstance(std::string& dir) const
+{
+  return vsSetupAPIHelper.GetVSInstanceInfo(dir);
+}
+
 bool cmGlobalVisualStudio15Generator::InitializeWindows(cmMakefile* mf)
 {
   // If the Win 8.1 SDK is installed then we can select a SDK matching
diff --git a/Source/cmGlobalVisualStudio15Generator.h b/Source/cmGlobalVisualStudio15Generator.h
index e934882..852a4e7 100644
--- a/Source/cmGlobalVisualStudio15Generator.h
+++ b/Source/cmGlobalVisualStudio15Generator.h
@@ -27,6 +27,11 @@ public:
   virtual void WriteSLNHeader(std::ostream& fout);
 
   virtual const char* GetToolsVersion() { return "15.0"; }
+
+  bool SetGeneratorInstance(std::string const& i, cmMakefile* mf) override;
+
+  bool GetVSInstance(std::string& dir) const;
+
 protected:
   bool InitializeWindows(cmMakefile* mf) override;
   virtual bool SelectWindowsStoreToolset(std::string& toolset) const;
diff --git a/Source/cmMakefile.cxx b/Source/cmMakefile.cxx
index 5643c97..b2641d2 100644
--- a/Source/cmMakefile.cxx
+++ b/Source/cmMakefile.cxx
@@ -3186,6 +3186,7 @@ int cmMakefile::TryCompile(const std::string& srcdir,
   // do a configure
   cm.SetHomeDirectory(srcdir);
   cm.SetHomeOutputDirectory(bindir);
+  cm.SetGeneratorInstance(this->GetSafeDefinition("CMAKE_GENERATOR_INSTANCE"));
   cm.SetGeneratorPlatform(this->GetSafeDefinition("CMAKE_GENERATOR_PLATFORM"));
   cm.SetGeneratorToolset(this->GetSafeDefinition("CMAKE_GENERATOR_TOOLSET"));
   cm.LoadCache();
diff --git a/Source/cmVSSetupHelper.cxx b/Source/cmVSSetupHelper.cxx
index ea13649..c2f8deb 100644
--- a/Source/cmVSSetupHelper.cxx
+++ b/Source/cmVSSetupHelper.cxx
@@ -80,6 +80,14 @@ cmVSSetupAPIHelper::~cmVSSetupAPIHelper()
     CoUninitialize();
 }
 
+bool cmVSSetupAPIHelper::SetVSInstance(std::string const& vsInstallLocation)
+{
+  this->SpecifiedVSInstallLocation = vsInstallLocation;
+  cmSystemTools::ConvertToUnixSlashes(this->SpecifiedVSInstallLocation);
+  chosenInstanceInfo = VSInstanceInfo();
+  return this->EnumerateAndChooseVSInstance();
+}
+
 bool cmVSSetupAPIHelper::IsVS2017Installed()
 {
   return this->EnumerateAndChooseVSInstance();
@@ -265,13 +273,6 @@ bool cmVSSetupAPIHelper::EnumerateAndChooseVSInstance()
   if (cmSystemTools::GetEnv("VS150COMNTOOLS", envVSCommonToolsDir)) {
     cmSystemTools::ConvertToUnixSlashes(envVSCommonToolsDir);
   }
-  // FIXME: If the environment variable value changes between runs
-  // of CMake within a given build tree the results are not defined.
-  // Instead we should save a CMAKE_GENERATOR_INSTANCE value in the cache
-  // (similar to CMAKE_GENERATOR_TOOLSET) to hold it persistently.
-  // Unfortunately doing so will require refactoring elsewhere in
-  // order to make sure the value is available in time to create
-  // the generator.
 
   std::vector<VSInstanceInfo> vecVSInstances;
   SmartCOMPtr<IEnumSetupInstances> enumInstances = NULL;
@@ -296,16 +297,29 @@ bool cmVSSetupAPIHelper::EnumerateAndChooseVSInstance()
     instance = instance2 = NULL;
 
     if (isInstalled) {
-      if (!envVSCommonToolsDir.empty()) {
+      if (!this->SpecifiedVSInstallLocation.empty()) {
+        // We are looking for a specific instance.
         std::string currentVSLocation = instanceInfo.GetInstallLocation();
-        currentVSLocation += "/Common7/Tools";
         if (cmSystemTools::ComparePath(currentVSLocation,
-                                       envVSCommonToolsDir)) {
+                                       this->SpecifiedVSInstallLocation)) {
           chosenInstanceInfo = instanceInfo;
           return true;
         }
+      } else {
+        // We are not looking for a specific instance.
+        // If we've been given a hint then use it.
+        if (!envVSCommonToolsDir.empty()) {
+          std::string currentVSLocation = instanceInfo.GetInstallLocation();
+          currentVSLocation += "/Common7/Tools";
+          if (cmSystemTools::ComparePath(currentVSLocation,
+                                         envVSCommonToolsDir)) {
+            chosenInstanceInfo = instanceInfo;
+            return true;
+          }
+        }
+        // Otherwise, add this to the list of candidates.
+        vecVSInstances.push_back(instanceInfo);
       }
-      vecVSInstances.push_back(instanceInfo);
     }
   }
 
diff --git a/Source/cmVSSetupHelper.h b/Source/cmVSSetupHelper.h
index 74a7ec0..c07cfaf 100644
--- a/Source/cmVSSetupHelper.h
+++ b/Source/cmVSSetupHelper.h
@@ -126,6 +126,8 @@ public:
   cmVSSetupAPIHelper();
   ~cmVSSetupAPIHelper();
 
+  bool SetVSInstance(std::string const& vsInstallLocation);
+
   bool IsVS2017Installed();
   bool GetVSInstanceInfo(std::string& vsInstallLocation);
   bool IsWin10SDKInstalled();
@@ -150,6 +152,8 @@ private:
   HRESULT comInitialized;
   // current best instance of VS selected
   VSInstanceInfo chosenInstanceInfo;
+
+  std::string SpecifiedVSInstallLocation;
 };
 
 #endif
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 =
diff --git a/Source/cmake.h b/Source/cmake.h
index ed3ebe0..5c5a90d 100644
--- a/Source/cmake.h
+++ b/Source/cmake.h
@@ -203,6 +203,12 @@ public:
   ///! Get the names of the current registered generators
   void GetRegisteredGenerators(std::vector<GeneratorInfo>& generators) const;
 
+  ///! Set the name of the selected generator-specific instance.
+  void SetGeneratorInstance(std::string const& instance)
+  {
+    this->GeneratorInstance = instance;
+  }
+
   ///! Set the name of the selected generator-specific platform.
   void SetGeneratorPlatform(std::string const& ts)
   {
@@ -431,6 +437,7 @@ protected:
 
   cmGlobalGenerator* GlobalGenerator;
   std::map<std::string, DiagLevel> DiagLevels;
+  std::string GeneratorInstance;
   std::string GeneratorPlatform;
   std::string GeneratorToolset;
 
diff --git a/Tests/RunCMake/CMakeLists.txt b/Tests/RunCMake/CMakeLists.txt
index 7eafa06..b70aeb9 100644
--- a/Tests/RunCMake/CMakeLists.txt
+++ b/Tests/RunCMake/CMakeLists.txt
@@ -15,6 +15,7 @@ macro(add_RunCMake_test test)
   add_test(NAME RunCMake.${test} COMMAND ${CMAKE_CMAKE_COMMAND}
     -DCMAKE_MODULE_PATH=${CMAKE_CURRENT_SOURCE_DIR}
     -DRunCMake_GENERATOR=${CMAKE_GENERATOR}
+    -DRunCMake_GENERATOR_INSTANCE=${CMAKE_GENERATOR_INSTANCE}
     -DRunCMake_GENERATOR_PLATFORM=${CMAKE_GENERATOR_PLATFORM}
     -DRunCMake_GENERATOR_TOOLSET=${CMAKE_GENERATOR_TOOLSET}
     -DRunCMake_MAKE_PROGRAM=${CMake_TEST_EXPLICIT_MAKE_PROGRAM}
@@ -47,6 +48,7 @@ function(add_RunCMake_test_group test types)
         -DTEST_TYPE=${type}
         -DCMAKE_MODULE_PATH=${CMAKE_CURRENT_SOURCE_DIR}
         -DRunCMake_GENERATOR=${CMAKE_GENERATOR}
+        -DRunCMake_GENERATOR_INSTANCE=${CMAKE_GENERATOR_INSTANCE}
         -DRunCMake_GENERATOR_PLATFORM=${CMAKE_GENERATOR_PLATFORM}
         -DRunCMake_GENERATOR_TOOLSET=${CMAKE_GENERATOR_TOOLSET}
         -DRunCMake_MAKE_PROGRAM=${CMake_TEST_EXPLICIT_MAKE_PROGRAM}
@@ -146,6 +148,7 @@ if(NOT CMAKE_C_COMPILER_ID MATCHES "Watcom")
   add_RunCMake_test(GenerateExportHeader)
 endif()
 add_RunCMake_test(GeneratorExpression)
+add_RunCMake_test(GeneratorInstance)
 add_RunCMake_test(GeneratorPlatform)
 add_RunCMake_test(GeneratorToolset)
 add_RunCMake_test(GetPrerequisites)
diff --git a/Tests/RunCMake/GeneratorInstance/BadInstance-result.txt b/Tests/RunCMake/GeneratorInstance/BadInstance-result.txt
new file mode 100644
index 0000000..d00491f
--- /dev/null
+++ b/Tests/RunCMake/GeneratorInstance/BadInstance-result.txt
@@ -0,0 +1 @@
+1
diff --git a/Tests/RunCMake/GeneratorInstance/BadInstance-stderr.txt b/Tests/RunCMake/GeneratorInstance/BadInstance-stderr.txt
new file mode 100644
index 0000000..5d01c4f
--- /dev/null
+++ b/Tests/RunCMake/GeneratorInstance/BadInstance-stderr.txt
@@ -0,0 +1,10 @@
+CMake Error at CMakeLists.txt:[0-9]+ \(project\):
+  Generator
+
+    .*
+
+  does not support instance specification, but instance
+
+    Bad Instance
+
+  was specified.$
diff --git a/Tests/RunCMake/GeneratorInstance/BadInstance-toolchain.cmake b/Tests/RunCMake/GeneratorInstance/BadInstance-toolchain.cmake
new file mode 100644
index 0000000..1d99259
--- /dev/null
+++ b/Tests/RunCMake/GeneratorInstance/BadInstance-toolchain.cmake
@@ -0,0 +1 @@
+set(CMAKE_GENERATOR_INSTANCE "Bad Instance")
diff --git a/Tests/RunCMake/GeneratorInstance/BadInstance.cmake b/Tests/RunCMake/GeneratorInstance/BadInstance.cmake
new file mode 100644
index 0000000..2fc38e5
--- /dev/null
+++ b/Tests/RunCMake/GeneratorInstance/BadInstance.cmake
@@ -0,0 +1 @@
+message(FATAL_ERROR "This should not be reached!")
diff --git a/Tests/RunCMake/GeneratorInstance/BadInstanceToolchain-result.txt b/Tests/RunCMake/GeneratorInstance/BadInstanceToolchain-result.txt
new file mode 100644
index 0000000..d00491f
--- /dev/null
+++ b/Tests/RunCMake/GeneratorInstance/BadInstanceToolchain-result.txt
@@ -0,0 +1 @@
+1
diff --git a/Tests/RunCMake/GeneratorInstance/BadInstanceToolchain-stderr.txt b/Tests/RunCMake/GeneratorInstance/BadInstanceToolchain-stderr.txt
new file mode 100644
index 0000000..5d01c4f
--- /dev/null
+++ b/Tests/RunCMake/GeneratorInstance/BadInstanceToolchain-stderr.txt
@@ -0,0 +1,10 @@
+CMake Error at CMakeLists.txt:[0-9]+ \(project\):
+  Generator
+
+    .*
+
+  does not support instance specification, but instance
+
+    Bad Instance
+
+  was specified.$
diff --git a/Tests/RunCMake/GeneratorInstance/BadInstanceToolchain.cmake b/Tests/RunCMake/GeneratorInstance/BadInstanceToolchain.cmake
new file mode 100644
index 0000000..2fc38e5
--- /dev/null
+++ b/Tests/RunCMake/GeneratorInstance/BadInstanceToolchain.cmake
@@ -0,0 +1 @@
+message(FATAL_ERROR "This should not be reached!")
diff --git a/Tests/RunCMake/GeneratorInstance/CMakeLists.txt b/Tests/RunCMake/GeneratorInstance/CMakeLists.txt
new file mode 100644
index 0000000..d3137f6
--- /dev/null
+++ b/Tests/RunCMake/GeneratorInstance/CMakeLists.txt
@@ -0,0 +1,3 @@
+cmake_minimum_required(VERSION 3.9)
+project(${RunCMake_TEST} NONE)
+include(${RunCMake_TEST}.cmake)
diff --git a/Tests/RunCMake/GeneratorInstance/DefaultInstance.cmake b/Tests/RunCMake/GeneratorInstance/DefaultInstance.cmake
new file mode 100644
index 0000000..7750c2e
--- /dev/null
+++ b/Tests/RunCMake/GeneratorInstance/DefaultInstance.cmake
@@ -0,0 +1,13 @@
+if("x${CMAKE_GENERATOR_INSTANCE}" STREQUAL "x")
+  message(FATAL_ERROR "CMAKE_GENERATOR_INSTANCE is empty but should have a value.")
+elseif("x${CMAKE_GENERATOR_INSTANCE}" MATCHES [[\\]])
+  message(FATAL_ERROR
+    "CMAKE_GENERATOR_INSTANCE is\n"
+    "  ${CMAKE_GENERATOR_INSTANCE}\n"
+    "which contains a backslash.")
+elseif(NOT IS_DIRECTORY "${CMAKE_GENERATOR_INSTANCE}")
+  message(FATAL_ERROR
+    "CMAKE_GENERATOR_INSTANCE is\n"
+    "  ${CMAKE_GENERATOR_INSTANCE}\n"
+    "which is not an existing directory.")
+endif()
diff --git a/Tests/RunCMake/GeneratorInstance/MissingInstance-result.txt b/Tests/RunCMake/GeneratorInstance/MissingInstance-result.txt
new file mode 100644
index 0000000..d00491f
--- /dev/null
+++ b/Tests/RunCMake/GeneratorInstance/MissingInstance-result.txt
@@ -0,0 +1 @@
+1
diff --git a/Tests/RunCMake/GeneratorInstance/MissingInstance-stderr.txt b/Tests/RunCMake/GeneratorInstance/MissingInstance-stderr.txt
new file mode 100644
index 0000000..623bf2e
--- /dev/null
+++ b/Tests/RunCMake/GeneratorInstance/MissingInstance-stderr.txt
@@ -0,0 +1,8 @@
+CMake Error at CMakeLists.txt:[0-9]+ \(project\):
+  Generator
+
+    .*
+
+  could not find specified instance of .*:
+
+    .*/Tests/RunCMake/GeneratorInstance/instance_does_not_exist$
diff --git a/Tests/RunCMake/GeneratorInstance/MissingInstance-toolchain.cmake b/Tests/RunCMake/GeneratorInstance/MissingInstance-toolchain.cmake
new file mode 100644
index 0000000..f803f14
--- /dev/null
+++ b/Tests/RunCMake/GeneratorInstance/MissingInstance-toolchain.cmake
@@ -0,0 +1 @@
+set(CMAKE_GENERATOR_INSTANCE "${CMAKE_CURRENT_LIST_DIR}/instance_does_not_exist")
diff --git a/Tests/RunCMake/GeneratorInstance/MissingInstance.cmake b/Tests/RunCMake/GeneratorInstance/MissingInstance.cmake
new file mode 100644
index 0000000..2fc38e5
--- /dev/null
+++ b/Tests/RunCMake/GeneratorInstance/MissingInstance.cmake
@@ -0,0 +1 @@
+message(FATAL_ERROR "This should not be reached!")
diff --git a/Tests/RunCMake/GeneratorInstance/MissingInstanceToolchain-result.txt b/Tests/RunCMake/GeneratorInstance/MissingInstanceToolchain-result.txt
new file mode 100644
index 0000000..d00491f
--- /dev/null
+++ b/Tests/RunCMake/GeneratorInstance/MissingInstanceToolchain-result.txt
@@ -0,0 +1 @@
+1
diff --git a/Tests/RunCMake/GeneratorInstance/MissingInstanceToolchain-stderr.txt b/Tests/RunCMake/GeneratorInstance/MissingInstanceToolchain-stderr.txt
new file mode 100644
index 0000000..623bf2e
--- /dev/null
+++ b/Tests/RunCMake/GeneratorInstance/MissingInstanceToolchain-stderr.txt
@@ -0,0 +1,8 @@
+CMake Error at CMakeLists.txt:[0-9]+ \(project\):
+  Generator
+
+    .*
+
+  could not find specified instance of .*:
+
+    .*/Tests/RunCMake/GeneratorInstance/instance_does_not_exist$
diff --git a/Tests/RunCMake/GeneratorInstance/MissingInstanceToolchain.cmake b/Tests/RunCMake/GeneratorInstance/MissingInstanceToolchain.cmake
new file mode 100644
index 0000000..2fc38e5
--- /dev/null
+++ b/Tests/RunCMake/GeneratorInstance/MissingInstanceToolchain.cmake
@@ -0,0 +1 @@
+message(FATAL_ERROR "This should not be reached!")
diff --git a/Tests/RunCMake/GeneratorInstance/NoInstance-result.txt b/Tests/RunCMake/GeneratorInstance/NoInstance-result.txt
new file mode 100644
index 0000000..d00491f
--- /dev/null
+++ b/Tests/RunCMake/GeneratorInstance/NoInstance-result.txt
@@ -0,0 +1 @@
+1
diff --git a/Tests/RunCMake/GeneratorInstance/NoInstance-stderr.txt b/Tests/RunCMake/GeneratorInstance/NoInstance-stderr.txt
new file mode 100644
index 0000000..e7b52fd
--- /dev/null
+++ b/Tests/RunCMake/GeneratorInstance/NoInstance-stderr.txt
@@ -0,0 +1,4 @@
+CMake Error at NoInstance.cmake:2 \(message\):
+  CMAKE_GENERATOR_INSTANCE is empty as expected.
+Call Stack \(most recent call first\):
+  CMakeLists.txt:3 \(include\)
diff --git a/Tests/RunCMake/GeneratorInstance/NoInstance.cmake b/Tests/RunCMake/GeneratorInstance/NoInstance.cmake
new file mode 100644
index 0000000..2e6782e
--- /dev/null
+++ b/Tests/RunCMake/GeneratorInstance/NoInstance.cmake
@@ -0,0 +1,7 @@
+if("x${CMAKE_GENERATOR_INSTANCE}" STREQUAL "x")
+  message(FATAL_ERROR "CMAKE_GENERATOR_INSTANCE is empty as expected.")
+else()
+  message(FATAL_ERROR
+    "CMAKE_GENERATOR_INSTANCE is \"${CMAKE_GENERATOR_INSTANCE}\" "
+    "but should be empty!")
+endif()
diff --git a/Tests/RunCMake/GeneratorInstance/RunCMakeTest.cmake b/Tests/RunCMake/GeneratorInstance/RunCMakeTest.cmake
new file mode 100644
index 0000000..e7f9ccb
--- /dev/null
+++ b/Tests/RunCMake/GeneratorInstance/RunCMakeTest.cmake
@@ -0,0 +1,22 @@
+include(RunCMake)
+
+if("${RunCMake_GENERATOR}" MATCHES "^Visual Studio 1[56789]")
+  set(RunCMake_GENERATOR_INSTANCE "")
+  run_cmake(DefaultInstance)
+
+  set(RunCMake_GENERATOR_INSTANCE "${RunCMake_SOURCE_DIR}/instance_does_not_exist")
+  run_cmake(MissingInstance)
+  set(RunCMake_TEST_OPTIONS -DCMAKE_TOOLCHAIN_FILE=${RunCMake_SOURCE_DIR}/MissingInstance-toolchain.cmake)
+  run_cmake(MissingInstanceToolchain)
+  unset(RunCMake_TEST_OPTIONS)
+else()
+  set(RunCMake_GENERATOR_INSTANCE "")
+  run_cmake(NoInstance)
+
+  set(RunCMake_GENERATOR_INSTANCE "Bad Instance")
+  run_cmake(BadInstance)
+
+  set(RunCMake_TEST_OPTIONS -DCMAKE_TOOLCHAIN_FILE=${RunCMake_SOURCE_DIR}/BadInstance-toolchain.cmake)
+  run_cmake(BadInstanceToolchain)
+  unset(RunCMake_TEST_OPTIONS)
+endif()
diff --git a/Tests/RunCMake/RunCMake.cmake b/Tests/RunCMake/RunCMake.cmake
index 4fd816e..e688830 100644
--- a/Tests/RunCMake/RunCMake.cmake
+++ b/Tests/RunCMake/RunCMake.cmake
@@ -79,11 +79,17 @@ function(run_cmake test)
       ${maybe_timeout}
       )
   else()
+    if(RunCMake_GENERATOR_INSTANCE)
+      set(_D_CMAKE_GENERATOR_INSTANCE "-DCMAKE_GENERATOR_INSTANCE=${RunCMake_GENERATOR_INSTANCE}")
+    else()
+      set(_D_CMAKE_GENERATOR_INSTANCE "")
+    endif()
     execute_process(
       COMMAND ${CMAKE_COMMAND} "${RunCMake_TEST_SOURCE_DIR}"
                 -G "${RunCMake_GENERATOR}"
                 -A "${RunCMake_GENERATOR_PLATFORM}"
                 -T "${RunCMake_GENERATOR_TOOLSET}"
+                ${_D_CMAKE_GENERATOR_INSTANCE}
                 -DRunCMake_TEST=${test}
                 --no-warn-unused-cli
                 ${RunCMake_TEST_OPTIONS}