ENH: Improve warning about specifying a cmake version

- Update policy CMP0000 to require use of the command
    cmake_minimum_required and not cmake_policy
    so there is only one way to avoid it.
  - Explicitly specify the line users should add.
  - Reference policy CMP0000 only at the end.
  - Fix policy CMP0000 documentation to not suggest
    use of the cmake_policy command.

Source/cmListFileCache.cxx

@@ -19,6 +19,7 @@
 #include "cmListFileLexer.h"
 #include "cmSystemTools.h"
 #include "cmMakefile.h"
+#include "cmVersion.h"
 
 #include <cmsys/RegularExpression.hxx>
 
@@ -121,43 +122,43 @@ bool cmListFile::ParseFile(const char* filename,
   // do we need a cmake_policy(VERSION call?
   if(topLevel)
   {
-    bool hasPolicy = false;
+    bool hasVersion = false;
     // search for the right policy command
     for(std::vector<cmListFileFunction>::iterator i 
           = this->Functions.begin();
         i != this->Functions.end(); ++i)
     {
-      if (cmSystemTools::LowerCase(i->Name) == "cmake_policy" &&
-          i->Arguments.size() && 
-          cmSystemTools::LowerCase(i->Arguments[0].Value) == "version")
-      {
-        hasPolicy = true;
-        break;
-      }
       if (cmSystemTools::LowerCase(i->Name) == "cmake_minimum_required")
       {
-        hasPolicy = true;
+        hasVersion = true;
         break;
       }
     }
-    // if no policy command is found this is an error
+    // if no version command is found this is a warning or error
-    if(!hasPolicy)
+    if(!hasVersion)
       {
+      cmOStringStream msg;
+      msg << "No cmake_minimum_required command is present.  "
+          << "A line of code such as\n"
+          << "  cmake_minimum_required(VERSION "
+          << cmVersion::GetMajorVersion() << "."
+          << cmVersion::GetMinorVersion()
+          << ")\n"
+          << "should be added at the top of the file.  "
+          << "The version specified may be lower if you wish to "
+          << "support older CMake versions for this project.  "
+          << "For more information run "
+          << "\"cmake --help-policy CMP0000\".";
       switch (mf->GetPolicyStatus(cmPolicies::CMP0000))
         {
         case cmPolicies::WARN:
-          mf->IssueMessage(cmake::AUTHOR_WARNING,
+          mf->IssueMessage(cmake::AUTHOR_WARNING, msg.str().c_str());
-            mf->GetPolicies()->GetPolicyWarning(cmPolicies::CMP0000)
+        case cmPolicies::OLD:
-            );
-
           // Implicitly set the version for the user.
           mf->SetPolicyVersion("2.4");
-        case cmPolicies::OLD:
           break;
         default:
-          mf->IssueMessage(cmake::FATAL_ERROR,
+          mf->IssueMessage(cmake::FATAL_ERROR, msg.str().c_str());
-            mf->GetPolicies()->GetRequiredPolicyError(cmPolicies::CMP0000)
-            );
           return false;
         }
       }

Source/cmPolicies.cxx

@@ -87,25 +87,21 @@ cmPolicies::cmPolicies()
   // define all the policies
   this->DefinePolicy(
     CMP0000, "CMP0000",
-    "A policy version number must be specified.",
+    "A minimum required CMake version must be specified.",
     "CMake requires that projects specify the version of CMake to which "
     "they have been written.  "
-    "This policy has been put in place to help existing projects build with "
+    "This policy has been put in place so users trying to build the project "
-    "new CMake versions as it evolves.  "
+    "may be told when they need to update their CMake.  "
-    "The easiest way to specify a policy version number is to "
+    "Specifying a version also helps the project build with CMake versions "
-    "call the cmake_minimum_required command at the top of "
+    "newer than that specified.  "
-    "your CMakeLists.txt file:\n"
+    "Use the cmake_minimum_required command at the top of your main "
+    " CMakeLists.txt file:\n"
     "  cmake_minimum_required(VERSION <major>.<minor>)\n"
     "where \"<major>.<minor>\" is the version of CMake you want to support "
     "(such as \"2.6\").  "
     "The command will ensure that at least the given version of CMake is "
-    "running and set the policy version.  "
+    "running and help newer versions be compatible with the project.  "
-    "See documentation of cmake_minimum_required for details.  "
+    "See documentation of cmake_minimum_required for details.",
-    "The cmake_policy command may be used at any time to set the "
-    "policy version:\n"
-    "  cmake_policy(VERSION <major>.<minor>)\n"
-    "This is the recommended way to set the policy version except at "
-    "the very top of a project.",
     2,6,0, cmPolicies::WARN
     );
 
@@ -549,14 +545,18 @@ void cmPolicies::GetDocumentation(std::vector<cmDocumentationEntry>& v)
     full << i->second->LongDescription;
     full << "\nThis policy was introduced in CMake version ";
     full << i->second->GetVersionString() << ".";
-    full << "CMake version " << cmVersion::GetMajorVersion()
+    if(i->first != cmPolicies::CMP0000)
+      {
+      full << "  "
+           << "CMake version " << cmVersion::GetMajorVersion()
            << "." << cmVersion::GetMinorVersion() << " ";
       // add in some more text here based on status
       switch (i->second->Status)
         {
         case cmPolicies::WARN:
-        full << "defaults to WARN for this policy.  "
+          full << "warns when the policy is not set and uses OLD behavior.  "
-             << "Use the cmake_policy command to set it to OLD or NEW.";
+               << "Use the cmake_policy command to set it to OLD or NEW "
+               << "explicitly.";
           break;
         case cmPolicies::OLD:
           full << "defaults to the OLD behavior for this policy.";
@@ -573,7 +573,7 @@ void cmPolicies::GetDocumentation(std::vector<cmDocumentationEntry>& v)
                << "Use the cmake_policy command to set it to NEW.";
           break;
         }
-          
+      }
     cmDocumentationEntry e(i->second->IDString.c_str(),
                            i->second->ShortDescription.c_str(),
                            full.str().c_str());