mirror of
https://github.com/Kitware/CMake.git
synced 2026-01-06 13:51:33 -06:00
195d47e213
Previously the `CMAKE_GENERATOR_INSTANCE` value was used only to filter the instances reported by the Visual Studio Installer tool. If the specified install location is not known to the VS Installer, but the user provided a `version=` field, check for the installation directly on disk. Fixes: #21639, #22197
61 lines
2.4 KiB
ReStructuredText
61 lines
2.4 KiB
ReStructuredText
CMAKE_GENERATOR_INSTANCE
|
|
------------------------
|
|
|
|
.. versionadded:: 3.11
|
|
|
|
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 via the
|
|
:envvar:`CMAKE_GENERATOR_INSTANCE` environment variable), 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.
|
|
|
|
Visual Studio Instance Selection
|
|
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
|
|
|
: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.
|