CMAKE_GENERATOR_INSTANCE¶
New in version 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
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 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¶
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>.<date>.<build>
New in version 3.23.
Specify the 4-component VS Build Version, a.k.a. Build Number. The components are:
<major>.<minor>
The VS major and minor version numbers. These are the same as the release version numbers.
<date>
A build date in the format
MMMDD
, whereMMM
is a month index since an epoch used by Microsoft, andDD
is a day in that month.<build>
A build index on the day represented by
<date>
.The build number is reported by
vswhere
asinstallationVersion
. For example, VS 16.11.10 has build number16.11.32126.315
.
New in version 3.23: A portable VS instance, which is not known to the Visual Studio Installer,
may be specified by providing both location
and version=
.
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.