Help/variable/CMAKE_GENERATOR_TOOLSET.rst

   1 CMAKE_GENERATOR_TOOLSET
   2 -----------------------
   3
   4 Native build system toolset specification provided by user.
   5
   6 Some CMake generators support a toolset specification to tell the
   7 native build system how to choose a compiler.  If the user specifies
   8 a toolset (e.g. via the :option:`cmake -T` option or via
   9 the :envvar:`CMAKE_GENERATOR_TOOLSET` environment variable) the value
  10 will be available in this variable.
  11
  12 The value of this variable should never be modified by project code.
  13 A toolchain file specified by the :variable:`CMAKE_TOOLCHAIN_FILE`
  14 variable may initialize ``CMAKE_GENERATOR_TOOLSET``.  Once a given
  15 build tree has been initialized with a particular value for this
  16 variable, changing the value has undefined behavior.
  17
  18 Toolset specification is supported only on specific generators:
  19
  20 * :ref:`Visual Studio Generators` for VS 2010 and above
  21 * The :generator:`Xcode` generator for Xcode 3.0 and above
  22 * The :generator:`Green Hills MULTI` generator
  23
  24 See native build system documentation for allowed toolset names.
  25
  26 Visual Studio Toolset Selection
  27 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  28
  29 The :ref:`Visual Studio Generators` support toolset specification
  30 using one of these forms:
  31
  32 * ``toolset``
  33 * ``toolset[,key=value]*``
  34 * ``key=value[,key=value]*``
  35
  36 The ``toolset`` specifies the toolset name.  The selected toolset name
  37 is provided in the :variable:`CMAKE_VS_PLATFORM_TOOLSET` variable.
  38
  39 The ``key=value`` pairs form a comma-separated list of options to
  40 specify generator-specific details of the toolset selection.
  41 Supported pairs are:
  42
  43 ``cuda=<version>|<path>``
  44   Specify the CUDA toolkit version to use or the path to a
  45   standalone CUDA toolkit directory.  Supported by VS 2010
  46   and above. The version can only be used with the CUDA
  47   toolkit VS integration globally installed.
  48   See the :variable:`CMAKE_VS_PLATFORM_TOOLSET_CUDA` and
  49   :variable:`CMAKE_VS_PLATFORM_TOOLSET_CUDA_CUSTOM_DIR` variables.
  50
  51 ``host=<arch>``
  52   Specify the host tools architecture as ``x64`` or ``x86``.
  53   Supported by VS 2013 and above.
  54   See the :variable:`CMAKE_VS_PLATFORM_TOOLSET_HOST_ARCHITECTURE`
  55   variable.
  56
  57 ``version=<version>``
  58   Specify the toolset version to use.  Supported by VS 2017
  59   and above with the specified toolset installed.
  60   See the :variable:`CMAKE_VS_PLATFORM_TOOLSET_VERSION` variable.
  61
  62 ``VCTargetsPath=<path>``
  63   Specify an alternative ``VCTargetsPath`` value for Visual Studio
  64   project files.  This allows use of VS platform extension configuration
  65   files (``.props`` and ``.targets``) that are not installed with VS.
  66
  67 Visual Studio Toolset Customization
  68 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  69
  70 **These are unstable interfaces with no compatibility guarantees**
  71 because they hook into undocumented internal CMake implementation details.
  72 Institutions may use these to internally maintain support for non-public
  73 Visual Studio platforms and toolsets, but must accept responsibility to
  74 make updates as changes are made to CMake.
  75
  76 Additional ``key=value`` pairs are available:
  77
  78 ``customFlagTableDir=<path>``
  79   .. versionadded:: 3.21
  80
  81   Specify the absolute path to a directory from which to load custom
  82   flag tables stored as JSON documents with file names of the form
  83   ``<platform>_<toolset>_<tool>.json`` or ``<platform>_<tool>.json``,
  84   where ``<platform>`` is the :variable:`CMAKE_VS_PLATFORM_NAME`,
  85   ``<toolset>`` is the :variable:`CMAKE_VS_PLATFORM_TOOLSET`,
  86   and ``<tool>`` is the tool for which the flag table is meant.
  87   **This naming pattern is an internal CMake implementation detail.**
  88   The ``<tool>`` names are undocumented.  The format of the ``.json``
  89   flag table files is undocumented.