Document reading LOCATION early as undefined (#11671)

Reading the LOCATION target property currently locks down the result and
ignores any later changes to properties that affect it.  This may or may
not be expected and may or may not be the behavior in earlier versions
of CMake.  The property is documented as provided only for compatibility
with CMake 2.4 and alternative interfaces are now available for all
originally envisioned use cases.  We want to discourage its use without
outright deprecating it.  Add documentation to explicitly state that
reading the property before other properties are set is undefined.

1 files changed, 11 insertions, 1 deletions

diff --git a/Source/cmTarget.cxx b/Source/cmTarget.cxx
index 9a698c0..7617cca 100644
--- a/Source/cmTarget.cxx
+++ b/Source/cmTarget.cxx
@@ -517,7 +517,17 @@ 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."
+     "\n"
+     "Do not read this property until after all other properties that can "
+     "affect the location of the target have been set.  "
+     "These include properties whose names match "
+     "\"(IMPLIB_)?(PREFIX|SUFFIX)\" or "
+     "\"(RUNTIME|LIBRARY|ARCHIVE)_OUTPUT_(NAME|DIRECTORY)(_<CONFIG>)?\".  "
+     "Failure to follow this rule is not diagnosed and leaves the location "
+     "of the target undefined.");
 
   cm->DefineProperty
     ("LOCATION_<CONFIG>", cmProperty::TARGET,