VS: Provide an option to use x64 host tools

Visual Studio provides toolchains that are themselves built for 32-bit
or 64-bit host architectures.  By default it uses the 32-bit tools, but
it can be told to prefer the 64-bit tools on 64-bit hosts.  Extend the
`CMAKE_GENERATOR_TOOLSET` specification to provide a way to request
use of the 64-bit host tools.

Closes: #15622

7 files changed, 34 insertions, 0 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 12 2013.rst b/Help/generator/Visual Studio 12 2013.rst
index c7358b9..5071b20 100644
--- a/Help/generator/Visual Studio 12 2013.rst
+++ b/Help/generator/Visual Studio 12 2013.rst
@@ -24,3 +24,5 @@ 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 0d776e9..64254b5 100644
--- a/Help/generator/Visual Studio 14 2015.rst
+++ b/Help/generator/Visual Studio 14 2015.rst
@@ -21,3 +21,5 @@ 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 5bd1882..2eb9052 100644
--- a/Help/generator/Visual Studio 15.rst
+++ b/Help/generator/Visual Studio 15.rst
@@ -21,3 +21,5 @@ 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/manual/cmake-variables.7.rst b/Help/manual/cmake-variables.7.rst
index f76c467..ef7f0c0 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).