Help: Document property redefinition semantics

Add a section to the `define_property()` documentation which
details the behavior when attempting to redefine an existing
property. (The command is silently ignored.)

Provide an example using `get_property()` to examine a property
definition created with `define_property()`.
This commit is contained in:
FeRD (Frank Dana)
2024-01-06 04:19:45 -05:00
parent 7aacae4e0e
commit 6c3311d53b

View File

@@ -74,6 +74,42 @@ project via corresponding options to the :command:`get_property` command.
underscore. It is recommended that the property name have a prefix specific
to the project.
Property Redefinition
^^^^^^^^^^^^^^^^^^^^^
Once a property is defined for a particular type of scope, it cannot be
redefined. Attempts to redefine an existing property by calling
:command:`define_property` with the same scope type and property name
will be silently ignored. Defining the same property name for two different
kinds of scope is valid.
:command:`get_property` can be used to determine whether a property is
already defined for a particular kind of scope, and if so, to examine its
definition. For example:
.. code-block:: cmake
# Initial definition
define_property(TARGET PROPERTY MY_NEW_PROP
BRIEF_DOCS "My new custom property"
)
# Later examination
get_property(my_new_prop_exists
TARGET NONE
PROPERTY MY_NEW_PROP
DEFINED
)
if(my_new_prop_exists)
get_property(my_new_prop_docs
TARGET NONE
PROPERTY MY_NEW_PROP
BRIEF_DOCS
)
# ${my_new_prop_docs} is now set to "My new custom property"
endif()
See Also
^^^^^^^^