| 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>.<date>.<build>`` |
| .. versionadded:: 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``, where ``MMM`` is a month index |
| since an epoch used by Microsoft, and ``DD`` is a day in that month. |
| |
| ``<build>`` |
| |
| A build index on the day represented by ``<date>``. |
| |
| The build number is reported by ``vswhere`` as ``installationVersion``. |
| For example, VS 16.11.10 has build number ``16.11.32126.315``. |
| |
| .. versionadded:: 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. |