load_command: Deprecate and document pending removal

This command works only when building projects using the same
architecture as the running CMake binary.  Since it was introduced
CMake has learned macro() and function() to add commands, and the
execute_process() command to launch advanced external computations.

Add a RunCMake.load_command test to verify the warning appears.

Source/cmLoadCommandCommand.cxx

@@ -224,6 +224,10 @@ cmLoadedCommand::~cmLoadedCommand()
 bool cmLoadCommandCommand
 ::InitialPass(std::vector<std::string> const& args, cmExecutionStatus &)
 {
+  this->Makefile->IssueMessage(
+    cmake::AUTHOR_WARNING,
+    "The \"load_command\" command will be removed in CMake 3.0.  "
+    "See command documentation for details.");
   if(args.size() < 1 )
     {
     return true;

Source/cmLoadCommandCommand.h

@@ -47,7 +47,7 @@ public:
    */
   virtual const char* GetTerseDocumentation() const
     {
-    return "Load a command into a running CMake.";
+    return "Deprecated.  Use macro() or function() instead.";
     }
 
   /**
@@ -56,6 +56,13 @@ public:
   virtual const char* GetFullDocumentation() const
     {
     return
+      "This command will be removed in CMake 3.0.  "
+      "It works only when the target architecture matches the "
+      "running CMake binary.  "
+      "Use macro() or function() to add commands.  "
+      "Use execute_process() to run advanced computations "
+      "in external processes."
+      "\n"
       "  load_command(COMMAND_NAME <loc1> [loc2 ...])\n"
       "The given locations are searched for a library whose name is "
       "cmCOMMAND_NAME.  If found, it is loaded as a module and the command "
@@ -67,6 +74,12 @@ public:
       "Otherwise the variable will not be set.";
     }
 
+  /** This command is kept for compatibility with older CMake versions. */
+  virtual bool IsDiscouraged() const
+    {
+    return true;
+    }
+
   cmTypeMacro(cmLoadCommandCommand, cmCommand);
 };
 

Tests/RunCMake/CMakeLists.txt

@@ -53,6 +53,7 @@ add_RunCMake_test(build_command)
 add_RunCMake_test(find_package)
 add_RunCMake_test(include)
 add_RunCMake_test(list)
+add_RunCMake_test(load_command)
 
 if("${CMAKE_TEST_GENERATOR}" MATCHES "Visual Studio [^6]")
   add_RunCMake_test(include_external_msproject)

Tests/RunCMake/load_command/CMakeLists.txt

@@ -0,0 +1,3 @@
+cmake_minimum_required(VERSION 2.8)
+project(${RunCMake_TEST} NONE)
+include(${RunCMake_TEST}.cmake)

Tests/RunCMake/load_command/LoadCommandDeprecated-stderr.txt

@@ -0,0 +1,6 @@
+CMake Warning \(dev\) at LoadCommandDeprecated.cmake:1 \(load_command\):
+  The "load_command" command will be removed in CMake 3.0.  See command
+  documentation for details.
+Call Stack \(most recent call first\):
+  CMakeLists.txt:3 \(include\)
+This warning is for project developers.  Use -Wno-dev to suppress it.

Tests/RunCMake/load_command/LoadCommandDeprecated.cmake

@@ -0,0 +1 @@
+load_command()

Tests/RunCMake/load_command/RunCMakeTest.cmake

@@ -0,0 +1,3 @@
+include(RunCMake)
+
+run_cmake(LoadCommandDeprecated)