VS: Add support for explicit 32-bit toolset selection via host=x86

Generalize the ``host=x64`` option in `CMAKE_GENERATOR_TOOLSET`
to also support ``host=x86``.

Help/generator/VS_TOOLSET_HOST_ARCH.txt

@@ -1,6 +1,7 @@
 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 a ``host=x64`` option to the toolset specification.
+(independent of the architecture they target).
+|VS_TOOLSET_HOST_ARCH_DEFAULT|
+One may explicitly request use of either the 32-bit or 64-bit host tools
+by adding either ``host=x86`` or ``host=x64`` to the toolset specification.
 See the :variable:`CMAKE_GENERATOR_TOOLSET` variable for details.

Help/generator/Visual Studio 12 2013.rst

@@ -42,4 +42,7 @@ 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.
 
+.. |VS_TOOLSET_HOST_ARCH_DEFAULT| replace::
+   By default this generator uses the 32-bit variant even on a 64-bit host.
+
 .. include:: VS_TOOLSET_HOST_ARCH.txt

Help/generator/Visual Studio 14 2015.rst

@@ -39,4 +39,7 @@ 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.
 
+.. |VS_TOOLSET_HOST_ARCH_DEFAULT| replace::
+   By default this generator uses the 32-bit variant even on a 64-bit host.
+
 .. include:: VS_TOOLSET_HOST_ARCH.txt

Help/generator/Visual Studio 15 2017.rst

@@ -56,4 +56,7 @@ The ``v141`` toolset that comes with Visual Studio 15 2017 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.
 
+.. |VS_TOOLSET_HOST_ARCH_DEFAULT| replace::
+   By default this generator uses the 32-bit variant even on a 64-bit host.
+
 .. include:: VS_TOOLSET_HOST_ARCH.txt

Help/generator/Visual Studio 16 2019.rst

@@ -46,4 +46,7 @@ The ``v142`` toolset that comes with Visual Studio 16 2019 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.
 
+.. |VS_TOOLSET_HOST_ARCH_DEFAULT| replace::
+   By default this generator uses the 32-bit variant even on a 64-bit host.
+
 .. include:: VS_TOOLSET_HOST_ARCH.txt

Help/variable/CMAKE_GENERATOR_TOOLSET.rst

@@ -44,8 +44,8 @@ Supported pairs are:
   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.
+``host=<arch>``
+  Specify the host tools architecture as ``x64`` or ``x86``.
   Supported by VS 2013 and above.
   See the :variable:`CMAKE_VS_PLATFORM_TOOLSET_HOST_ARCHITECTURE`
   variable.

Help/variable/CMAKE_VS_PLATFORM_TOOLSET_HOST_ARCHITECTURE.rst

@@ -3,8 +3,8 @@ 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=x64``
-value in the :variable:`CMAKE_GENERATOR_TOOLSET` option.  CMake provides
-the selected toolchain architecture preference in this variable (either
-``x64`` or empty).
+The :ref:`Visual Studio Generators` for VS 2013 and above support using
+either the 32-bit or 64-bit host toolchains by specifying a ``host=x86``
+or ``host=x64`` value in the :variable:`CMAKE_GENERATOR_TOOLSET` option.
+CMake provides the selected toolchain architecture preference in this
+variable (``x86``, ``x64``, or empty).

Source/cmGlobalVisualStudio12Generator.cxx

@@ -126,8 +126,8 @@ bool cmGlobalVisualStudio12Generator::MatchesGeneratorName(
 bool cmGlobalVisualStudio12Generator::ProcessGeneratorToolsetField(
   std::string const& key, std::string const& value)
 {
-  if (key == "host" && value == "x64") {
-    this->GeneratorToolsetHostArchitecture = "x64";
+  if (key == "host" && (value == "x64" || value == "x86")) {
+    this->GeneratorToolsetHostArchitecture = value;
     return true;
   }
   return this->cmGlobalVisualStudio11Generator::ProcessGeneratorToolsetField(

Tests/RunCMake/GeneratorToolset/BadToolsetHostArchTwice-stderr.txt

@@ -5,6 +5,6 @@ CMake Error at CMakeLists.txt:[0-9]+ \(project\):
 
   given toolset specification
 
-    Test Toolset,host=x64,host=x64
+    Test Toolset,host=x64,host=x86
 
   that contains duplicate field key 'host'\.$

Tests/RunCMake/GeneratorToolset/RunCMakeTest.cmake

@@ -16,14 +16,16 @@ if("${RunCMake_GENERATOR}" MATCHES "Visual Studio 1[012456]")
     set(RunCMake_GENERATOR_TOOLSET "Test Toolset,host=x64")
     run_cmake(TestToolsetHostArchBoth)
     set(RunCMake_GENERATOR_TOOLSET ",host=x64")
-    run_cmake(TestToolsetHostArchOnly)
+    run_cmake(TestToolsetHostArchOnly_x64)
     set(RunCMake_GENERATOR_TOOLSET "host=x64")
-    run_cmake(TestToolsetHostArchOnly)
+    run_cmake(TestToolsetHostArchOnly_x64)
+    set(RunCMake_GENERATOR_TOOLSET "host=x86")
+    run_cmake(TestToolsetHostArchOnly_x86)
     set(RunCMake_GENERATOR_TOOLSET "Test Toolset")
     run_cmake(TestToolsetHostArchNone)
     set(RunCMake_GENERATOR_TOOLSET "Test Toolset,host=x65")
     run_cmake(BadToolsetHostArch)
-    set(RunCMake_GENERATOR_TOOLSET "Test Toolset,host=x64,host=x64")
+    set(RunCMake_GENERATOR_TOOLSET "Test Toolset,host=x64,host=x86")
     run_cmake(BadToolsetHostArchTwice)
     if("${RunCMake_GENERATOR}" MATCHES "Visual Studio 1[56]")
       set(RunCMake_GENERATOR_TOOLSET "Test Toolset,version=Test Toolset Version")

Tests/RunCMake/GeneratorToolset/TestToolsetHostArchOnly_x86-stdout.txt

@@ -0,0 +1,2 @@
+-- CMAKE_VS_PLATFORM_TOOLSET='v[0-9]+'
+-- CMAKE_VS_PLATFORM_TOOLSET_HOST_ARCHITECTURE='x86'

Tests/RunCMake/GeneratorToolset/TestToolsetHostArchOnly_x86.cmake

@@ -0,0 +1,2 @@
+message(STATUS "CMAKE_VS_PLATFORM_TOOLSET='${CMAKE_VS_PLATFORM_TOOLSET}'")
+message(STATUS "CMAKE_VS_PLATFORM_TOOLSET_HOST_ARCHITECTURE='${CMAKE_VS_PLATFORM_TOOLSET_HOST_ARCHITECTURE}'")