Merge topic 'cleanup-define_property' into release-3.23

87c3b5e421 define_property(): Only test prefix if INITIALIZE_FROM_VARIABLE is given
9b50f221f6 Help: Update the main purpose of define_property()
e993e2c52c Help: Clean up INITIALIZE_FROM_VARIABLE define_property() option

Acked-by: Kitware Robot <[email protected]>
Tested-by: buildbot <[email protected]>
Acked-by: Kyle Edwards <[email protected]>
Merge-request: !7090

Help/command/define_property.rst

@@ -13,11 +13,13 @@ Define and document custom properties.
                    [INITIALIZE_FROM_VARIABLE <variable>])
 
 Defines one property in a scope for use with the :command:`set_property` and
-:command:`get_property` commands.  This is primarily useful to associate
-documentation with property names that may be retrieved with the
-:command:`get_property` command. The first argument determines the kind of
-scope in which the property should be used.  It must be one of the
-following:
+:command:`get_property` commands. It is mainly useful for defining the way
+a property is initialized or inherited. Historically, the command also
+associated documentation with a property, but that is no longer considered a
+primary use case.
+
+The first argument determines the kind of scope in which the property should
+be used.  It must be one of the following:
 
 ::
 
@@ -56,14 +58,16 @@ out the contents to append to.
 
 The ``BRIEF_DOCS`` and ``FULL_DOCS`` options are followed by strings to be
 associated with the property as its brief and full documentation.
-Corresponding options to the :command:`get_property` command will retrieve
-the documentation.
+CMake does not use this documentation other than making it available to the
+project via corresponding options to the :command:`get_property` command.
 
 .. versionchanged:: 3.23
 
   The ``BRIEF_DOCS`` and ``FULL_DOCS`` options are optional.
 
-The ``INITIALIZE_FROM_VARIABLE`` option is followed by the name of a variable
-from which to initialize the property. The variable name must end with the
-property name, must have a prefix before the property name, and must not begin
-with ``CMAKE_`` or ``_CMAKE_``.
+.. versionadded:: 3.23
+
+  The ``INITIALIZE_FROM_VARIABLE`` option specifies a variable from which the
+  property should be initialized. It can only be used with target properties.
+  The ``<variable>`` name must end with the property name, must have a prefix
+  before the property name, and must not begin with ``CMAKE_`` or ``_CMAKE_``.

Source/cmDefinePropertyCommand.cxx

@@ -97,20 +97,20 @@ bool cmDefinePropertyCommand(std::vector<std::string> const& args,
         PropertyName, "\""));
       return false;
     }
-  }
 
-  // Make sure the variable is not reserved.
-  static constexpr const char* reservedPrefixes[] = {
-    "CMAKE_",
-    "_CMAKE_",
-  };
-  if (std::any_of(std::begin(reservedPrefixes), std::end(reservedPrefixes),
-                  [&initializeFromVariable](const char* prefix) {
-                    return cmHasPrefix(initializeFromVariable, prefix);
-                  })) {
-    status.SetError(
-      cmStrCat("variable name \"", initializeFromVariable, "\" is reserved"));
-    return false;
+    // Make sure the variable is not reserved.
+    static constexpr const char* reservedPrefixes[] = {
+      "CMAKE_",
+      "_CMAKE_",
+    };
+    if (std::any_of(std::begin(reservedPrefixes), std::end(reservedPrefixes),
+                    [&initializeFromVariable](const char* prefix) {
+                      return cmHasPrefix(initializeFromVariable, prefix);
+                    })) {
+      status.SetError(cmStrCat("variable name \"", initializeFromVariable,
+                               "\" is reserved"));
+      return false;
+    }
   }
 
   // Actually define the property.