VS: Provide the default platform name to project code

The value of `CMAKE_VS_PLATFORM_NAME` is computed by Visual Studio
generators based on `CMAKE_GENERATOR_PLATFORM` or some default.
Prior to the VS 2019 generator, the default was always `Win32`.
However, for the `Visual Studio 16 2019` generator, the default is
based on the host platform.

Store the default in a new `CMAKE_VS_PLATFORM_NAME_DEFAULT` variable for
use by project code.  This is particularly useful in toolchain files
because they are allowed to set `CMAKE_GENERATOR_PLATFORM` and so
`CMAKE_VS_PLATFORM_NAME` is not yet known.  Of course the toolchain file
author knows whether it will set `CMAKE_GENERATOR_PLATFORM`, and if not
then `CMAKE_VS_PLATFORM_NAME_DEFAULT` provides the platform name that
will be used.

Fixes: #19177

5 files changed, 26 insertions, 2 deletions

diff --git a/Help/generator/Visual Studio 16 2019.rst b/Help/generator/Visual Studio 16 2019.rst
index b456554..4aec7f7 100644
--- a/Help/generator/Visual Studio 16 2019.rst
+++ b/Help/generator/Visual Studio 16 2019.rst
@@ -28,7 +28,8 @@ by default.
 Platform Selection
 ^^^^^^^^^^^^^^^^^^
 
-The default target platform name (architecture) is that of the host.
+The default target platform name (architecture) is that of the host
+and is provided in the :variable:`CMAKE_VS_PLATFORM_NAME_DEFAULT` variable.
 
 The :variable:`CMAKE_GENERATOR_PLATFORM` variable may be set, perhaps
 via the :manual:`cmake(1)` ``-A`` option, to specify a target platform
diff --git a/Help/manual/cmake-variables.7.rst b/Help/manual/cmake-variables.7.rst
index 6bb30cb..5c494b8 100644
--- a/Help/manual/cmake-variables.7.rst
+++ b/Help/manual/cmake-variables.7.rst
@@ -105,6 +105,7 @@ Variables that Provide Information
    /variable/CMAKE_VS_MSBUILD_COMMAND
    /variable/CMAKE_VS_NsightTegra_VERSION
    /variable/CMAKE_VS_PLATFORM_NAME
+   /variable/CMAKE_VS_PLATFORM_NAME_DEFAULT
    /variable/CMAKE_VS_PLATFORM_TOOLSET
    /variable/CMAKE_VS_PLATFORM_TOOLSET_CUDA
    /variable/CMAKE_VS_PLATFORM_TOOLSET_HOST_ARCHITECTURE
diff --git a/Help/release/3.14.rst b/Help/release/3.14.rst
index f2a91c6..c208304 100644
--- a/Help/release/3.14.rst
+++ b/Help/release/3.14.rst
@@ -137,6 +137,10 @@ Variables
   relocatable and reproducible builds that are invariant of the build
   directory.
 
+* A :variable:`CMAKE_VS_PLATFORM_NAME_DEFAULT` variable was added for
+  :ref:`Visual Studio Generators` to report their default platform used
+  when :variable:`CMAKE_GENERATOR_PLATFORM` is not set explicitly.
+
 Properties
 ----------
 
@@ -391,3 +395,10 @@ Changes made since CMake 3.14.0 include the following.
   our conventions.  3.14.1 revises the module to use ``Fontconfig_*``
   variable names.  This is incompatible with 3.14.0 but since the
   module is new in the 3.14 series usage should not yet be widespread.
+
+3.14.3
+------
+
+* The :variable:`CMAKE_VS_PLATFORM_NAME_DEFAULT` variable was added
+  to help toolchain files work with the :generator:`Visual Studio 16 2019`
+  generator where the default platform now depends on the host platform.
diff --git a/Help/variable/CMAKE_VS_PLATFORM_NAME.rst b/Help/variable/CMAKE_VS_PLATFORM_NAME.rst
index a532743..7a4642a 100644
--- a/Help/variable/CMAKE_VS_PLATFORM_NAME.rst
+++ b/Help/variable/CMAKE_VS_PLATFORM_NAME.rst
@@ -1,8 +1,10 @@
 CMAKE_VS_PLATFORM_NAME
 ----------------------
 
-Visual Studio target platform name.
+Visual Studio target platform name used by the current generator.
 
 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.
+
+See also the :variable:`CMAKE_VS_PLATFORM_NAME_DEFAULT` variable.
diff --git a/Help/variable/CMAKE_VS_PLATFORM_NAME_DEFAULT.rst b/Help/variable/CMAKE_VS_PLATFORM_NAME_DEFAULT.rst
new file mode 100644
index 0000000..c18e6fd
--- /dev/null
+++ b/Help/variable/CMAKE_VS_PLATFORM_NAME_DEFAULT.rst
@@ -0,0 +1,9 @@
+CMAKE_VS_PLATFORM_NAME_DEFAULT
+------------------------------
+
+Default for the Visual Studio target platform name for the current generator
+without considering the value of the :variable:`CMAKE_GENERATOR_PLATFORM`
+variable.  For :ref:`Visual Studio Generators` for VS 2017 and below this is
+always ``Win32``.  For VS 2019 and above this is based on the host platform.
+
+See also the :variable:`CMAKE_VS_PLATFORM_NAME` variable.