Merge topic 'doc-LOCATION-property-undefined-behavior'

5734497 Document reading LOCATION_<CONFIG> early as undefined (#11671)
7ffe6d7 Document reading LOCATION early as undefined (#11671)

Source/cmTarget.cxx

@@ -501,6 +501,15 @@ void cmTarget::DefineProperties(cmake *cm)
      "value is the default.  "
      "See documentation of CMAKE_<LANG>_LINKER_PREFERENCE variables.");
 
+#define CM_LOCATION_UNDEFINED_BEHAVIOR \
+  "\n" \
+  "Do not set properties that affect the location of the target after " \
+  "reading this property.  These include properties whose names match " \
+  "\"(RUNTIME|LIBRARY|ARCHIVE)_OUTPUT_(NAME|DIRECTORY)(_<CONFIG>)?\" " \
+  "or \"(IMPLIB_)?(PREFIX|SUFFIX)\".  " \
+  "Failure to follow this rule is not diagnosed and leaves the location " \
+  "of the target undefined."
+
   cm->DefineProperty
     ("LOCATION", cmProperty::TARGET,
      "Read-only location of a target on disk.",
@@ -517,7 +526,10 @@ void cmTarget::DefineProperties(cmake *cm)
      "In CMake 2.6 and above add_custom_command automatically recognizes a "
      "target name in its COMMAND and DEPENDS options and computes the "
      "target location.  "
-     "Therefore this property is not needed for creating custom commands.");
+     "In CMake 2.8.4 and above add_custom_command recognizes generator "
+     "expressions to refer to target locations anywhere in the command.  "
+     "Therefore this property is not needed for creating custom commands."
+     CM_LOCATION_UNDEFINED_BEHAVIOR);
 
   cm->DefineProperty
     ("LOCATION_<CONFIG>", cmProperty::TARGET,
@@ -530,7 +542,8 @@ void cmTarget::DefineProperties(cmake *cm)
      "By default CMake looks for an exact-match but otherwise uses an "
      "arbitrary available configuration.  "
      "Use the MAP_IMPORTED_CONFIG_<CONFIG> property to map imported "
-     "configurations explicitly.");
+     "configurations explicitly."
+     CM_LOCATION_UNDEFINED_BEHAVIOR);
 
   cm->DefineProperty
     ("LINK_DEPENDS", cmProperty::TARGET,