| define_property |
| --------------- |
| |
| Define and document custom properties. |
| |
| .. code-block:: cmake |
| |
| define_property(<GLOBAL | DIRECTORY | TARGET | SOURCE | |
| TEST | VARIABLE | CACHED_VARIABLE> |
| PROPERTY <name> [INHERITED] |
| [BRIEF_DOCS <brief-doc> [docs...]] |
| [FULL_DOCS <full-doc> [docs...]] |
| [INITIALIZE_FROM_VARIABLE <variable>]) |
| |
| Defines one property in a scope for use with the :command:`set_property` and |
| :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: |
| |
| :: |
| |
| GLOBAL = associated with the global namespace |
| DIRECTORY = associated with one directory |
| TARGET = associated with one target |
| SOURCE = associated with one source file |
| TEST = associated with a test named with add_test |
| VARIABLE = documents a CMake language variable |
| CACHED_VARIABLE = documents a CMake cache variable |
| |
| Note that unlike :command:`set_property` and :command:`get_property` no |
| actual scope needs to be given; only the kind of scope is important. |
| |
| The required ``PROPERTY`` option is immediately followed by the name of |
| the property being defined. |
| |
| If the ``INHERITED`` option is given, then the :command:`get_property` command |
| will chain up to the next higher scope when the requested property is not set |
| in the scope given to the command. |
| |
| * ``DIRECTORY`` scope chains to its parent directory's scope, continuing the |
| walk up parent directories until a directory has the property set or there |
| are no more parents. If still not found at the top level directory, it |
| chains to the ``GLOBAL`` scope. |
| * ``TARGET``, ``SOURCE`` and ``TEST`` properties chain to ``DIRECTORY`` scope, |
| including further chaining up the directories, etc. as needed. |
| |
| Note that this scope chaining behavior only applies to calls to |
| :command:`get_property`, :command:`get_directory_property`, |
| :command:`get_target_property`, :command:`get_source_file_property` and |
| :command:`get_test_property`. There is no inheriting behavior when *setting* |
| properties, so using ``APPEND`` or ``APPEND_STRING`` with the |
| :command:`set_property` command will not consider inherited values when working |
| 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. |
| 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. |
| |
| .. 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 and must not begin |
| with ``CMAKE_`` or ``_CMAKE_``. The property name must contain at least one |
| underscore. It is recommended that the property name have a prefix specific |
| to the project. |
| |
| See Also |
| ^^^^^^^^ |
| |
| * :command:`get_property` |
| * :command:`set_property` |