From 7ffe6d77da01674b1a67e518a83dab3b744d09b4 Mon Sep 17 00:00:00 2001 From: Brad King Date: Mon, 10 Jan 2011 10:46:15 -0500 Subject: 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. --- Source/cmTarget.cxx | 12 +++++++++++- 1 file changed, 11 insertions(+), 1 deletion(-) 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)(_)?\". " + "Failure to follow this rule is not diagnosed and leaves the location " + "of the target undefined."); cm->DefineProperty ("LOCATION_", cmProperty::TARGET, -- cgit v0.12 From 57344977f563b129b0c93d9fc60d75747a89dd8b Mon Sep 17 00:00:00 2001 From: Brad King Date: Mon, 10 Jan 2011 12:07:32 -0500 Subject: Document reading LOCATION_ early as undefined (#11671) Although the LOCATION property is for compatibility with CMake 2.4, the LOCATION_ property is modern. However, if a project reads it and sets location-altering properties later the behavior is undefined. See parent commit for details. --- Source/cmTarget.cxx | 21 ++++++++++++--------- 1 file changed, 12 insertions(+), 9 deletions(-) diff --git a/Source/cmTarget.cxx b/Source/cmTarget.cxx index 7617cca..52574e2 100644 --- a/Source/cmTarget.cxx +++ b/Source/cmTarget.cxx @@ -501,6 +501,15 @@ void cmTarget::DefineProperties(cmake *cm) "value is the default. " "See documentation of CMAKE__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)(_)?\" " \ + "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.", @@ -520,14 +529,7 @@ void cmTarget::DefineProperties(cmake *cm) "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)(_)?\". " - "Failure to follow this rule is not diagnosed and leaves the location " - "of the target undefined."); + CM_LOCATION_UNDEFINED_BEHAVIOR); cm->DefineProperty ("LOCATION_", cmProperty::TARGET, @@ -540,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_ property to map imported " - "configurations explicitly."); + "configurations explicitly." + CM_LOCATION_UNDEFINED_BEHAVIOR); cm->DefineProperty ("LINK_DEPENDS", cmProperty::TARGET, -- cgit v0.12