ENH: Finish creating, documenting, and enforcing policy CMP_0002.

Source/cmMakefile.cxx

@@ -3283,36 +3283,9 @@ bool cmMakefile::EnforceUniqueName(std::string const& name, std::string& msg,
         default: break;
         }
       e << "created in source directory \""
-        << existing->GetMakefile()->GetCurrentDirectory() << "\"."
-        << "\n";
-      e <<
-        "Logical target names must be globally unique because:\n"
-        "  - Unique names may be referenced unambiguously both in CMake\n"
-        "    code and on make tool command lines.\n"
-        "  - Logical names are used by Xcode and VS IDE generators\n"
-        "    to produce meaningful project names for the targets.\n"
-        "The logical name of executable and library targets does not "
-        "have to correspond to the physical file names built.  "
-        "Consider using the OUTPUT_NAME target property to create two "
-        "targets with the same physical name while keeping logical "
-        "names distinct.  "
-        "Custom targets must simply have globally unique names."
-        "\n"
-        "If you are building an older project it is possible that "
-        "it violated this rule but was working accidentally because "
-        "CMake did not previously diagnose this problem.\n";
-      if(isCustom && existing->GetType() == cmTarget::UTILITY)
-        {
-        e <<
-          "For projects that care only about Makefile generators and do "
-          "not wish to support Xcode or VS IDE generators, one may add\n"
-          "  set_property(GLOBAL PROPERTY ALLOW_DUPLICATE_CUSTOM_TARGETS 1)\n"
-          "to the top of the project to allow duplicate custom targets "
-          "(target names must still be unique within each directory).  "
-          "However, setting this property will cause non-Makefile generators "
-          "to produce an error and refuse to generate the project.";
-        }
-        msg = e.str();
+        << existing->GetMakefile()->GetCurrentDirectory() << "\".  "
+        << "See documentation for policy CMP_0002 for more details.";
+      msg = e.str();
       return false;
       }
     }

Source/cmPolicies.cxx

@@ -116,8 +116,23 @@ cmPolicies::cmPolicies()
 
   this->DefinePolicy(
     CMP_0002, "CMP_0002",
-    "CMake requires that target names be globaly unique.",
-    "....",
+    "Logical target names must be globally unique.",
+    "Targets names created with "
+    "add_executable, add_library, or add_custom_target "
+    "are logical build target names.  "
+    "Logical target names must be globally unique because:\n"
+    "  - Unique names may be referenced unambiguously both in CMake\n"
+    "    code and on make tool command lines.\n"
+    "  - Logical names are used by Xcode and VS IDE generators\n"
+    "    to produce meaningful project names for the targets.\n"
+    "The logical name of executable and library targets does not "
+    "have to correspond to the physical file names built.  "
+    "Consider using the OUTPUT_NAME target property to create two "
+    "targets with the same physical name while keeping logical "
+    "names distinct.  "
+    "Custom targets must simply have globally unique names (unless one "
+    "uses the global property ALLOW_DUPLICATE_CUSTOM_TARGETS with a "
+    "Makefiles generator).",
     2,6,0, cmPolicies::WARN
     );
 }

Source/cmPolicies.h

@@ -42,7 +42,11 @@ public:
   {
     CMP_0000, // Policy version specification
     CMP_0001, // Ignore old compatibility variable
-    CMP_0002
+    CMP_0002, // Target names must be unique
+
+    // Always the last entry.  Useful mostly to avoid adding a comma
+    // the last policy when adding a new one.
+    CMP_COUNT
   };
 
   ///! convert a string policy ID into a number

Source/cmake.cxx

@@ -3299,7 +3299,7 @@ void cmake::DefineProperties(cmake *cm)
     "ALLOW_DUPLICATE_CUSTOM_TARGETS", cmProperty::GLOBAL,
     "Allow duplicate custom targets to be created.",
     "Normally CMake requires that all targets built in a project have "
-    "globally unique names.  "
+    "globally unique logical names (see policy CMP_0002).  "
     "This is necessary to generate meaningful project file names in "
     "Xcode and VS IDE generators.  "
     "It also allows the target names to be referenced unambiguously.\n"
@@ -3309,7 +3309,7 @@ void cmake::DefineProperties(cmake *cm)
     "not wish to support Xcode or VS IDE generators, one may set this "
     "property to true to allow duplicate custom targets.  "
     "The property allows multiple add_custom_target command calls in "
-    "*different directories* to specify the same target name.  "
+    "different directories to specify the same target name.  "
     "However, setting this property will cause non-Makefile generators "
     "to produce an error and refuse to generate the project."
     );