diff options
| author | Brad King <brad.king@kitware.com> | 2017-10-04 17:01:47 (GMT) |
|---|---|---|
| committer | Brad King <brad.king@kitware.com> | 2017-10-19 14:20:12 (GMT) |
| commit | 9ffb35386fb923a5959eec482bfa131aa3feaa18 (patch) | |
| tree | a01b2cc99c387db8f4ef234d70ff35de43009b70 /Help | |
| parent | 17edfa41983c61574e897eda923c90fd33ba8ac3 (diff) | |
| download | CMake-9ffb35386fb923a5959eec482bfa131aa3feaa18.zip CMake-9ffb35386fb923a5959eec482bfa131aa3feaa18.tar.gz CMake-9ffb35386fb923a5959eec482bfa131aa3feaa18.tar.bz2 | |
VS: Select and save a VS 2017 instance persistently
Visual Studio 2017 supports multiple instances installed on a single
machine. We use the Visual Studio Installer tool to enumerate instances
and select one. Once we select an instance for a given build tree, save
the result in `CMAKE_GENERATOR_INSTANCE` so we can re-configure the tree
with the same instance on future re-runs of CMake.
Fixes: #17268
Diffstat (limited to 'Help')
| -rw-r--r-- | Help/generator/Visual Studio 15 2017.rst | 18 | ||||
| -rw-r--r-- | Help/release/dev/generator-instance.rst | 5 | ||||
| -rw-r--r-- | Help/variable/CMAKE_GENERATOR_INSTANCE.rst | 4 |
3 files changed, 17 insertions, 10 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/release/dev/generator-instance.rst b/Help/release/dev/generator-instance.rst index 5e92f7d..a3ff658 100644 --- a/Help/release/dev/generator-instance.rst +++ b/Help/release/dev/generator-instance.rst @@ -3,5 +3,6 @@ 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. + 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 index 7c2c280..78c81b1 100644 --- a/Help/variable/CMAKE_GENERATOR_INSTANCE.rst +++ b/Help/variable/CMAKE_GENERATOR_INSTANCE.rst @@ -17,6 +17,8 @@ for this variable, changing the value has undefined behavior. Instance specification is supported only on specific generators: -* None +* 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. |