1define_property
2---------------
3
4Define and document custom properties.
5
6.. code-block:: cmake
7
8  define_property(<GLOBAL | DIRECTORY | TARGET | SOURCE |
9                   TEST | VARIABLE | CACHED_VARIABLE>
10                   PROPERTY <name> [INHERITED]
11                   BRIEF_DOCS <brief-doc> [docs...]
12                   FULL_DOCS <full-doc> [docs...])
13
14Defines one property in a scope for use with the :command:`set_property` and
15:command:`get_property` commands.  This is primarily useful to associate
16documentation with property names that may be retrieved with the
17:command:`get_property` command. The first argument determines the kind of
18scope in which the property should be used.  It must be one of the
19following:
20
21::
22
23  GLOBAL    = associated with the global namespace
24  DIRECTORY = associated with one directory
25  TARGET    = associated with one target
26  SOURCE    = associated with one source file
27  TEST      = associated with a test named with add_test
28  VARIABLE  = documents a CMake language variable
29  CACHED_VARIABLE = documents a CMake cache variable
30
31Note that unlike :command:`set_property` and :command:`get_property` no
32actual scope needs to be given; only the kind of scope is important.
33
34The required ``PROPERTY`` option is immediately followed by the name of
35the property being defined.
36
37If the ``INHERITED`` option is given, then the :command:`get_property` command
38will chain up to the next higher scope when the requested property is not set
39in the scope given to the command.
40
41* ``DIRECTORY`` scope chains to its parent directory's scope, continuing the
42  walk up parent directories until a directory has the property set or there
43  are no more parents.  If still not found at the top level directory, it
44  chains to the ``GLOBAL`` scope.
45* ``TARGET``, ``SOURCE`` and ``TEST`` properties chain to ``DIRECTORY`` scope,
46  including further chaining up the directories, etc. as needed.
47
48Note that this scope chaining behavior only applies to calls to
49:command:`get_property`, :command:`get_directory_property`,
50:command:`get_target_property`, :command:`get_source_file_property` and
51:command:`get_test_property`.  There is no inheriting behavior when *setting*
52properties, so using ``APPEND`` or ``APPEND_STRING`` with the
53:command:`set_property` command will not consider inherited values when working
54out the contents to append to.
55
56The ``BRIEF_DOCS`` and ``FULL_DOCS`` options are followed by strings to be
57associated with the property as its brief and full documentation.
58Corresponding options to the :command:`get_property` command will retrieve
59the documentation.
60