Merge topic 'vs-host-x64-tools'

d079e71c VS: Provide an option to use x64 host tools
779939a0 Help: Document VS and Xcode toolset selection

11 files changed, 81 insertions, 6 deletions

diff --git a/Help/generator/VS_TOOLSET_HOST_ARCH.txt b/Help/generator/VS_TOOLSET_HOST_ARCH.txt
new file mode 100644
index 0000000..58e9223
--- /dev/null
+++ b/Help/generator/VS_TOOLSET_HOST_ARCH.txt
@@ -0,0 +1,10 @@
+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.
diff --git a/Help/generator/Visual Studio 10 2010.rst b/Help/generator/Visual Studio 10 2010.rst
index c694443..04eef10 100644
--- a/Help/generator/Visual Studio 10 2010.rst
+++ b/Help/generator/Visual Studio 10 2010.rst
@@ -17,3 +17,10 @@ a target platform name optionally at the end of this generator name:
 
 For compatibility with CMake versions prior to 3.0, one may specify this
 generator using the name ``Visual Studio 10`` without the year component.
+
+Toolset Selection
+^^^^^^^^^^^^^^^^^
+
+The ``v100`` toolset that comes with Visual Studio 10 2010 is selected by
+default.  The :variable:`CMAKE_GENERATOR_TOOLSET` option may be set, perhaps
+via the :manual:`cmake(1)` ``-T`` option, to specify another toolset.
diff --git a/Help/generator/Visual Studio 11 2012.rst b/Help/generator/Visual Studio 11 2012.rst
index 2f1e729..347a153 100644
--- a/Help/generator/Visual Studio 11 2012.rst
+++ b/Help/generator/Visual Studio 11 2012.rst
@@ -20,3 +20,10 @@ a target platform name optionally at the end of this generator name:
 
 For compatibility with CMake versions prior to 3.0, one may specify this
 generator using the name "Visual Studio 11" without the year component.
+
+Toolset Selection
+^^^^^^^^^^^^^^^^^
+
+The ``v110`` toolset that comes with Visual Studio 11 2012 is selected by
+default.  The :variable:`CMAKE_GENERATOR_TOOLSET` option may be set, perhaps
+via the :manual:`cmake(1)` ``-T`` option, to specify another toolset.
diff --git a/Help/generator/Visual Studio 12 2013.rst b/Help/generator/Visual Studio 12 2013.rst
index 6e8545b..5071b20 100644
--- a/Help/generator/Visual Studio 12 2013.rst
+++ b/Help/generator/Visual Studio 12 2013.rst
@@ -17,3 +17,12 @@ a target platform name optionally at the end of this generator name:
 
 For compatibility with CMake versions prior to 3.0, one may specify this
 generator using the name "Visual Studio 12" without the year component.
+
+Toolset Selection
+^^^^^^^^^^^^^^^^^
+
+The ``v120`` toolset that comes with Visual Studio 12 2013 is selected by
+default.  The :variable:`CMAKE_GENERATOR_TOOLSET` option may be set, perhaps
+via the :manual:`cmake(1)` ``-T`` option, to specify another toolset.
+
+.. include:: VS_TOOLSET_HOST_ARCH.txt
diff --git a/Help/generator/Visual Studio 14 2015.rst b/Help/generator/Visual Studio 14 2015.rst
index 707caf9..64254b5 100644
--- a/Help/generator/Visual Studio 14 2015.rst
+++ b/Help/generator/Visual Studio 14 2015.rst
@@ -14,3 +14,12 @@ a target platform name optionally at the end of this generator name:
 
 ``Visual Studio 14 2015 ARM``
   Specify target platform ``ARM``.
+
+Toolset Selection
+^^^^^^^^^^^^^^^^^
+
+The ``v140`` toolset that comes with Visual Studio 14 2015 is selected by
+default.  The :variable:`CMAKE_GENERATOR_TOOLSET` option may be set, perhaps
+via the :manual:`cmake(1)` ``-T`` option, to specify another toolset.
+
+.. include:: VS_TOOLSET_HOST_ARCH.txt
diff --git a/Help/generator/Visual Studio 15.rst b/Help/generator/Visual Studio 15.rst
index ae456eb..2eb9052 100644
--- a/Help/generator/Visual Studio 15.rst
+++ b/Help/generator/Visual Studio 15.rst
@@ -14,3 +14,12 @@ a target platform name optionally at the end of this generator name:
 
 ``Visual Studio 15 ARM``
   Specify target platform ``ARM``.
+
+Toolset Selection
+^^^^^^^^^^^^^^^^^
+
+The ``v141`` toolset that comes with Visual Studio 15 is selected by
+default.  The :variable:`CMAKE_GENERATOR_TOOLSET` option may be set, perhaps
+via the :manual:`cmake(1)` ``-T`` option, to specify another toolset.
+
+.. include:: VS_TOOLSET_HOST_ARCH.txt
diff --git a/Help/generator/Xcode.rst b/Help/generator/Xcode.rst
index d8a6790..25ff4c7 100644
--- a/Help/generator/Xcode.rst
+++ b/Help/generator/Xcode.rst
@@ -2,3 +2,10 @@ Xcode
 -----
 
 Generate Xcode project files.
+
+Toolset Selection
+^^^^^^^^^^^^^^^^^
+
+By default Xcode is allowed to select its own default toolchain.
+The :variable:`CMAKE_GENERATOR_TOOLSET` option may be set, perhaps
+via the :manual:`cmake(1)` ``-T`` option, to specify another toolset.
diff --git a/Help/manual/OPTIONS_BUILD.txt b/Help/manual/OPTIONS_BUILD.txt
index fa0e4c1..9b3f717 100644
--- a/Help/manual/OPTIONS_BUILD.txt
+++ b/Help/manual/OPTIONS_BUILD.txt
@@ -52,13 +52,12 @@
  Specify toolset name if supported by generator.
 
  Some CMake generators support a toolset name to be given to the
- native build system to choose a compiler.  This is supported only on
- specific generators:
-
- ::
+ native build system to choose a compiler.
+ See the :variable:`CMAKE_GENERATOR_TOOLSET` variable.
+ This is supported only on specific generators:
 
-   Visual Studio >= 10
-   Xcode >= 3.0
+ * :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.
 
diff --git a/Help/manual/cmake-variables.7.rst b/Help/manual/cmake-variables.7.rst
index 064a9e3..a5b1daa 100644
--- a/Help/manual/cmake-variables.7.rst
+++ b/Help/manual/cmake-variables.7.rst
@@ -82,6 +82,7 @@ Variables that Provide Information
    /variable/CMAKE_VS_NsightTegra_VERSION
    /variable/CMAKE_VS_PLATFORM_NAME
    /variable/CMAKE_VS_PLATFORM_TOOLSET
+   /variable/CMAKE_VS_PLATFORM_TOOLSET_HOST_ARCHITECTURE
    /variable/CMAKE_VS_WINDOWS_TARGET_PLATFORM_VERSION
    /variable/CMAKE_XCODE_PLATFORM_TOOLSET
    /variable/PROJECT_BINARY_DIR
diff --git a/Help/release/dev/vs-host-x64-tools.rst b/Help/release/dev/vs-host-x64-tools.rst
new file mode 100644
index 0000000..e42881a
--- /dev/null
+++ b/Help/release/dev/vs-host-x64-tools.rst
@@ -0,0 +1,7 @@
+vs-host-x64-tools
+-----------------
+
+* The :ref:`Visual Studio Generators` for VS 2013 and above learned to
+  support a ``host=x64`` option in the :variable:`CMAKE_GENERATOR_TOOLSET`
+  value (e.g.  via the :manual:`cmake(1)` ``-T`` option) to request use
+  of a VS 64-bit toolchain on 64-bit hosts.
diff --git a/Help/variable/CMAKE_VS_PLATFORM_TOOLSET_HOST_ARCHITECTURE.rst b/Help/variable/CMAKE_VS_PLATFORM_TOOLSET_HOST_ARCHITECTURE.rst
new file mode 100644
index 0000000..4c04e97
--- /dev/null
+++ b/Help/variable/CMAKE_VS_PLATFORM_TOOLSET_HOST_ARCHITECTURE.rst
@@ -0,0 +1,10 @@
+CMAKE_VS_PLATFORM_TOOLSET_HOST_ARCHITECTURE
+-------------------------------------------
+
+Visual Studio preferred tool architecture.
+
+The :ref:`Visual Studio Generators` for VS 2013 and above support optional
+selection of a 64-bit toolchain on 64-bit hosts by specifying a ``host=64``
+value in the :variable:`CMAKE_GENERATOR_TOOLSET` option.  CMake provides
+the selected toolchain architecture preference in this variable (either
+``x64`` or empty).