• Home
  • Line#
  • Scopes#
  • Navigate#
  • Raw
  • Download
1get_property
2------------
3
4Get a property.
5
6.. code-block:: cmake
7
8  get_property(<variable>
9               <GLOBAL             |
10                DIRECTORY [<dir>]  |
11                TARGET    <target> |
12                SOURCE    <source>
13                          [DIRECTORY <dir> | TARGET_DIRECTORY <target>] |
14                INSTALL   <file>   |
15                TEST      <test>   |
16                CACHE     <entry>  |
17                VARIABLE           >
18               PROPERTY <name>
19               [SET | DEFINED | BRIEF_DOCS | FULL_DOCS])
20
21Gets one property from one object in a scope.
22
23The first argument specifies the variable in which to store the result.
24The second argument determines the scope from which to get the property.
25It must be one of the following:
26
27``GLOBAL``
28  Scope is unique and does not accept a name.
29
30``DIRECTORY``
31  Scope defaults to the current directory but another
32  directory (already processed by CMake) may be named by the
33  full or relative path ``<dir>``.
34  Relative paths are treated as relative to the current source directory.
35  See also the :command:`get_directory_property` command.
36
37  .. versionadded:: 3.19
38    ``<dir>`` may reference a binary directory.
39
40``TARGET``
41  Scope must name one existing target.
42  See also the :command:`get_target_property` command.
43
44``SOURCE``
45  Scope must name one source file.  By default, the source file's property
46  will be read from the current source directory's scope.
47
48  .. versionadded:: 3.18
49    Directory scope can be overridden with one of the following sub-options:
50
51    ``DIRECTORY <dir>``
52      The source file property will be read from the ``<dir>`` directory's
53      scope.  CMake must already know about
54      the directory, either by having added it through a call
55      to :command:`add_subdirectory` or ``<dir>`` being the top level directory.
56      Relative paths are treated as relative to the current source directory.
57
58      .. versionadded:: 3.19
59        ``<dir>`` may reference a binary directory.
60
61    ``TARGET_DIRECTORY <target>``
62      The source file property will be read from the directory scope in which
63      ``<target>`` was created (``<target>`` must therefore already exist).
64
65  See also the :command:`get_source_file_property` command.
66
67``INSTALL``
68  .. versionadded:: 3.1
69
70  Scope must name one installed file path.
71
72``TEST``
73  Scope must name one existing test.
74  See also the :command:`get_test_property` command.
75
76``CACHE``
77  Scope must name one cache entry.
78
79``VARIABLE``
80  Scope is unique and does not accept a name.
81
82The required ``PROPERTY`` option is immediately followed by the name of
83the property to get.  If the property is not set an empty value is
84returned, although some properties support inheriting from a parent scope
85if defined to behave that way (see :command:`define_property`).
86
87If the ``SET`` option is given the variable is set to a boolean
88value indicating whether the property has been set.  If the ``DEFINED``
89option is given the variable is set to a boolean value indicating
90whether the property has been defined such as with the
91:command:`define_property` command.
92
93If ``BRIEF_DOCS`` or ``FULL_DOCS`` is given then the variable is set to a
94string containing documentation for the requested property.  If
95documentation is requested for a property that has not been defined
96``NOTFOUND`` is returned.
97
98.. note::
99
100  The :prop_sf:`GENERATED` source file property may be globally visible.
101  See its documentation for details.
102