cmake: Add -A option to specify a generator platform

Define the 'cmake -A' option to set CMAKE_GENERATOR_PLATFORM
without having to spell out the whole variable name.  We choose
the name '-A' for "platform" because '-P' is already taken, and
in the common use case the "platform" is actually an architecture
(e.g. x64).

Teach the RunCMake test infrastructure to use -A to pass the generator
platform.  Extend the RunCMake.GeneratorPlatform test with a case to
verify that the -A option cannot be repeated.

10 files changed, 49 insertions, 2 deletions

diff --git a/Help/manual/OPTIONS_BUILD.txt b/Help/manual/OPTIONS_BUILD.txt
index 2079c44..363d0aa 100644
--- a/Help/manual/OPTIONS_BUILD.txt
+++ b/Help/manual/OPTIONS_BUILD.txt
@@ -51,6 +51,17 @@
 
  See native build system documentation for allowed toolset names.
 
+``-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.  This is supported only on
+ specific generators::
+
+   Visual Studio >= 8
+
+ See native build system documentation for allowed platform names.
+
 ``-Wno-dev``
  Suppress developer warnings.
 
diff --git a/Help/release/dev/vs-generator-platform.rst b/Help/release/dev/vs-generator-platform.rst
index df90e19..cf2090b 100644
--- a/Help/release/dev/vs-generator-platform.rst
+++ b/Help/release/dev/vs-generator-platform.rst
@@ -4,4 +4,6 @@ vs-generator-platform
 * The Visual Studio generators for versions 8 (2005) and above
   learned to read the target platform name from a new
   :variable:`CMAKE_GENERATOR_PLATFORM` variable when it is
-  not specified as part of the generator name.
+  not specified as part of the generator name.  The platform
+  name may be specified on the :manual:`cmake(1)` command line
+  with the ``-A`` option, e.g. ``-G "Visual Studio 12 2013" -A x64``.
diff --git a/Help/variable/CMAKE_GENERATOR_PLATFORM.rst b/Help/variable/CMAKE_GENERATOR_PLATFORM.rst
index 44d7fc4..5809b6a 100644
--- a/Help/variable/CMAKE_GENERATOR_PLATFORM.rst
+++ b/Help/variable/CMAKE_GENERATOR_PLATFORM.rst
@@ -5,6 +5,8 @@ Generator-specific target platform name specified by user.
 
 Some CMake generators support a target platform name to be given
 to the native build system to choose a compiler toolchain.
+If the user specifies a toolset name (e.g. via the cmake -A 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`
diff --git a/Source/cmake.cxx b/Source/cmake.cxx
index c9c63c7..09d270d 100644
--- a/Source/cmake.cxx
+++ b/Source/cmake.cxx
@@ -639,6 +639,7 @@ void cmake::SetArgs(const std::vector<std::string>& args,
 {
   bool directoriesSet = directoriesSetBefore;
   bool haveToolset = false;
+  bool havePlatform = false;
   for(unsigned int i=1; i < args.size(); ++i)
     {
     std::string arg = args[i];
@@ -767,6 +768,27 @@ void cmake::SetArgs(const std::vector<std::string>& args,
                    "uninitialized variables.\n";
       this->SetCheckSystemVars(true);
       }
+    else if(arg.find("-A",0) == 0)
+      {
+      std::string value = arg.substr(2);
+      if(value.size() == 0)
+        {
+        ++i;
+        if(i >= args.size())
+          {
+          cmSystemTools::Error("No platform specified for -A");
+          return;
+          }
+        value = args[i];
+        }
+      if(havePlatform)
+        {
+        cmSystemTools::Error("Multiple -A options not allowed");
+        return;
+        }
+      this->GeneratorPlatform = value;
+      havePlatform = true;
+      }
     else if(arg.find("-T",0) == 0)
       {
       std::string value = arg.substr(2);
diff --git a/Source/cmake.h b/Source/cmake.h
index 919fc24..60ffcd4 100644
--- a/Source/cmake.h
+++ b/Source/cmake.h
@@ -476,6 +476,7 @@ private:
   {"-U <globbing_expr>", "Remove matching entries from CMake cache."}, \
   {"-G <generator-name>", "Specify a build system generator."},\
   {"-T <toolset-name>", "Specify toolset name if supported by generator."}, \
+  {"-A <platform-name>", "Specify platform name if supported by generator."}, \
   {"-Wno-dev", "Suppress developer warnings."},\
   {"-Wdev", "Enable developer warnings."}
 
diff --git a/Tests/RunCMake/GeneratorPlatform/RunCMakeTest.cmake b/Tests/RunCMake/GeneratorPlatform/RunCMakeTest.cmake
index 89cc712..76045f0 100644
--- a/Tests/RunCMake/GeneratorPlatform/RunCMakeTest.cmake
+++ b/Tests/RunCMake/GeneratorPlatform/RunCMakeTest.cmake
@@ -10,3 +10,9 @@ else()
   set(RunCMake_GENERATOR_PLATFORM "Bad Platform")
   run_cmake(BadPlatform)
 endif()
+
+set(RunCMake_GENERATOR_TOOLSET "")
+
+set(RunCMake_TEST_OPTIONS -A "Extra Platform")
+run_cmake(TwoPlatforms)
+unset(RunCMake_TEST_OPTIONS)
diff --git a/Tests/RunCMake/GeneratorPlatform/TwoPlatforms-result.txt b/Tests/RunCMake/GeneratorPlatform/TwoPlatforms-result.txt
new file mode 100644
index 0000000..d00491f
--- /dev/null
+++ b/Tests/RunCMake/GeneratorPlatform/TwoPlatforms-result.txt
@@ -0,0 +1 @@
+1
diff --git a/Tests/RunCMake/GeneratorPlatform/TwoPlatforms-stderr.txt b/Tests/RunCMake/GeneratorPlatform/TwoPlatforms-stderr.txt
new file mode 100644
index 0000000..90e4eca
--- /dev/null
+++ b/Tests/RunCMake/GeneratorPlatform/TwoPlatforms-stderr.txt
@@ -0,0 +1 @@
+CMake Error: Multiple -A options not allowed
diff --git a/Tests/RunCMake/GeneratorPlatform/TwoPlatforms.cmake b/Tests/RunCMake/GeneratorPlatform/TwoPlatforms.cmake
new file mode 100644
index 0000000..2fc38e5
--- /dev/null
+++ b/Tests/RunCMake/GeneratorPlatform/TwoPlatforms.cmake
@@ -0,0 +1 @@
+message(FATAL_ERROR "This should not be reached!")
diff --git a/Tests/RunCMake/RunCMake.cmake b/Tests/RunCMake/RunCMake.cmake
index abc3e3d..56d69c8 100644
--- a/Tests/RunCMake/RunCMake.cmake
+++ b/Tests/RunCMake/RunCMake.cmake
@@ -53,7 +53,7 @@ function(run_cmake test)
     execute_process(
       COMMAND ${CMAKE_COMMAND} "${RunCMake_TEST_SOURCE_DIR}"
                 -G "${RunCMake_GENERATOR}"
-                "-DCMAKE_GENERATOR_PLATFORM=${RunCMake_GENERATOR_PLATFORM}"
+                -A "${RunCMake_GENERATOR_PLATFORM}"
                 -T "${RunCMake_GENERATOR_TOOLSET}"
                 -DRunCMake_TEST=${test}
                 --no-warn-unused-cli