Merge topic 'doc-vs-toolset-options'

3df2506f Help: Document VS generator toolset specification syntax
60546b48 Help: Cross-reference generator toolset variables
35c5cddc Help: Cross-reference generator platform variables
7df38939 Help: Move generator toolset support details to variable docs
c750b282 Help: Move generator platform support details to variable docs

Acked-by: Kitware Robot <kwrobot@kitware.com>
Merge-request: !580

6 files changed, 65 insertions, 30 deletions

diff --git a/Help/generator/VS_TOOLSET_HOST_ARCH.txt b/Help/generator/VS_TOOLSET_HOST_ARCH.txt
index 58e9223..5d13e77 100644
--- a/Help/generator/VS_TOOLSET_HOST_ARCH.txt
+++ b/Help/generator/VS_TOOLSET_HOST_ARCH.txt
@@ -2,9 +2,5 @@ For each toolset that comes with this version of Visual Studio, there are
 variants that are themselves compiled for 32-bit (x86) and 64-bit (x64) hosts
 (independent of the architecture they target).  By default Visual Studio
 chooses the 32-bit variant even on a 64-bit host.  One may request use of the
-64-bit host tools by adding ``host=x64`` to the toolset specification:
-
-``host=x64``
-  Select the 64-bit variant of the default toolset.
-``<toolset>,host=x64``
-  Select the 64-bit variant of the ``<toolset>`` toolset.
+64-bit host tools by adding a ``host=x64`` option to the toolset specification.
+See the :variable:`CMAKE_GENERATOR_TOOLSET` variable for details.
diff --git a/Help/manual/OPTIONS_BUILD.txt b/Help/manual/OPTIONS_BUILD.txt
index 9b3f717..e8b87c9 100644
--- a/Help/manual/OPTIONS_BUILD.txt
+++ b/Help/manual/OPTIONS_BUILD.txt
@@ -48,31 +48,19 @@
  build system.  Possible generator names are specified in the
  :manual:`cmake-generators(7)` manual.
 
-``-T <toolset-name>``
- Specify toolset name if supported by generator.
+``-T <toolset-spec>``
+ Toolset specification for the generator, if supported.
 
- Some CMake generators support a toolset name to be given to the
- native build system to choose a compiler.
- See the :variable:`CMAKE_GENERATOR_TOOLSET` variable.
- This is supported only on specific generators:
-
- * :ref:`Visual Studio Generators` for VS 2010 and above
- * The :generator:`Xcode` generator for Xcode 3.0 and above
-
- See native build system documentation for allowed toolset names.
+ Some CMake generators support a toolset specification to tell
+ the native build system how to choose a compiler.  See the
+ :variable:`CMAKE_GENERATOR_TOOLSET` variable for details.
 
 ``-A <platform-name>``
  Specify platform name if supported by generator.
 
  Some CMake generators support a platform name to be given to the
  native build system to choose a compiler or SDK.  See the
- :variable:`CMAKE_GENERATOR_PLATFORM` variable.
- This is supported only on specific generators:
-
- * For :ref:`Visual Studio Generators` with VS 2005 and above this
-   specifies the target architecture.
-
- See native build system documentation for allowed platform names.
+ :variable:`CMAKE_GENERATOR_PLATFORM` variable for details.
 
 ``-Wno-dev``
  Suppress developer warnings.
diff --git a/Help/variable/CMAKE_GENERATOR_PLATFORM.rst b/Help/variable/CMAKE_GENERATOR_PLATFORM.rst
index a5c284a..50412ff 100644
--- a/Help/variable/CMAKE_GENERATOR_PLATFORM.rst
+++ b/Help/variable/CMAKE_GENERATOR_PLATFORM.rst
@@ -1,7 +1,7 @@
 CMAKE_GENERATOR_PLATFORM
 ------------------------
 
-Generator-specific target platform name specified by user.
+Generator-specific target platform specification provided by user.
 
 Some CMake generators support a target platform name to be given
 to the native build system to choose a compiler toolchain.
@@ -13,3 +13,16 @@ A toolchain file specified by the :variable:`CMAKE_TOOLCHAIN_FILE`
 variable may initialize ``CMAKE_GENERATOR_PLATFORM``.  Once a given
 build tree has been initialized with a particular value for this
 variable, changing the value has undefined behavior.
+
+Platform specification is supported only on specific generators:
+
+* For :ref:`Visual Studio Generators` with VS 2005 and above this
+  specifies the target architecture.
+
+See native build system documentation for allowed platform names.
+
+Visual Studio Platform Selection
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+On :ref:`Visual Studio Generators` the selected platform name
+is provided in the :variable:`CMAKE_VS_PLATFORM_NAME` variable.
diff --git a/Help/variable/CMAKE_GENERATOR_TOOLSET.rst b/Help/variable/CMAKE_GENERATOR_TOOLSET.rst
index 89abe54..11c37d7 100644
--- a/Help/variable/CMAKE_GENERATOR_TOOLSET.rst
+++ b/Help/variable/CMAKE_GENERATOR_TOOLSET.rst
@@ -1,15 +1,50 @@
 CMAKE_GENERATOR_TOOLSET
 -----------------------
 
-Native build system toolset name specified by user.
+Native build system toolset specification provided by user.
 
-Some CMake generators support a toolset name to be given to the native
-build system to choose a compiler.  If the user specifies a toolset
-name (e.g.  via the :manual:`cmake(1)` ``-T`` option) the value will be
-available in this variable.
+Some CMake generators support a toolset specification to tell the
+native build system how to choose a compiler.  If the user specifies
+a toolset (e.g.  via the :manual:`cmake(1)` ``-T`` option) 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_TOOLSET``.  Once a given
 build tree has been initialized with a particular value for this
 variable, changing the value has undefined behavior.
+
+Toolset specification is supported only on specific generators:
+
+* :ref:`Visual Studio Generators` for VS 2010 and above
+* The :generator:`Xcode` generator for Xcode 3.0 and above
+
+See native build system documentation for allowed toolset names.
+
+Visual Studio Toolset Selection
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+The :ref:`Visual Studio Generators` support toolset specification
+using one of these forms:
+
+* ``toolset``
+* ``toolset[,key=value]*``
+* ``key=value[,key=value]*``
+
+The ``toolset`` specifies the toolset name.  The selected toolset name
+is provided in the :variable:`CMAKE_VS_PLATFORM_TOOLSET` variable.
+
+The ``key=value`` pairs form a comma-separated list of options to
+specify generator-specific details of the toolset selection.
+Supported pairs are:
+
+``cuda=<version>``
+  Specify the CUDA toolkit version to use.  Supported by VS 2010
+  and above with the CUDA toolkit VS integration installed.
+  See the :variable:`CMAKE_VS_PLATFORM_TOOLSET_CUDA` variable.
+
+``host=x64``
+  Request use of the native ``x64`` toolchain on ``x64`` hosts.
+  Supported by VS 2013 and above.
+  See the :variable:`CMAKE_VS_PLATFORM_TOOLSET_HOST_ARCHITECTURE`
+  variable.
diff --git a/Help/variable/CMAKE_VS_PLATFORM_NAME.rst b/Help/variable/CMAKE_VS_PLATFORM_NAME.rst
index c6f8d41..a532743 100644
--- a/Help/variable/CMAKE_VS_PLATFORM_NAME.rst
+++ b/Help/variable/CMAKE_VS_PLATFORM_NAME.rst
@@ -5,3 +5,4 @@ Visual Studio target platform name.
 
 VS 8 and above allow project files to specify a target platform.
 CMake provides the name of the chosen platform in this variable.
+See the :variable:`CMAKE_GENERATOR_PLATFORM` variable for details.
diff --git a/Help/variable/CMAKE_VS_PLATFORM_TOOLSET.rst b/Help/variable/CMAKE_VS_PLATFORM_TOOLSET.rst
index 144a41d..ed2d3f3 100644
--- a/Help/variable/CMAKE_VS_PLATFORM_TOOLSET.rst
+++ b/Help/variable/CMAKE_VS_PLATFORM_TOOLSET.rst
@@ -8,3 +8,5 @@ compiler toolchains.  CMake may specify a toolset explicitly, such as
 ``v110`` for VS 11 or ``Windows7.1SDK`` for 64-bit support in VS 10
 Express.  CMake provides the name of the chosen toolset in this
 variable.
+
+See the :variable:`CMAKE_GENERATOR_TOOLSET` variable for details.