1
0
mirror of https://github.com/Kitware/CMake.git synced 2025-10-20 04:24:36 +08:00

Help: Clarify behavior of INHERITED properties

Fixes: #17839
This commit is contained in:
Craig Scott
2018-03-21 21:32:21 +11:00
parent 9cc97ab4dc
commit ff6234509e
7 changed files with 71 additions and 24 deletions

View File

@@ -34,10 +34,24 @@ 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 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
``GLOBAL``. ``TARGET``, ``SOURCE``, and ``TEST`` chain to ``DIRECTORY``.
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.

View File

@@ -7,11 +7,16 @@ Get a property of ``DIRECTORY`` scope.
get_directory_property(<variable> [DIRECTORY <dir>] <prop-name>)
Store a property of directory scope in the named variable. If the
property is not defined the empty-string is returned. The ``DIRECTORY``
argument specifies another directory from which to retrieve the
property value. The specified directory must have already been
traversed by CMake.
Store a property of directory scope in the named ``<variable>``.
The ``DIRECTORY`` argument specifies another directory from which
to retrieve the property value instead of the current directory.
The specified directory must have already been traversed by CMake.
If the property is not defined for the nominated directory scope,
an empty string is returned. In the case of ``INHERITED`` properties,
if the property is not found for the nominated directory scope,
the search will chain to a parent scope as described for the
:command:`define_property` command.
::

View File

@@ -50,7 +50,10 @@ be one of the following:
The required ``PROPERTY`` option is immediately followed by the name of
the property to get. If the property is not set an empty value is
returned. If the ``SET`` option is given the variable is set to a boolean
returned, although some properties support inheriting from a parent scope
if defined to behave that way (see :command:`define_property`).
If the ``SET`` option is given the variable is set to a boolean
value indicating whether the property has been set. If the ``DEFINED``
option is given the variable is set to a boolean value indicating
whether the property has been defined such as with the

View File

@@ -8,9 +8,15 @@ Get a property for a source file.
get_source_file_property(VAR file property)
Get a property from a source file. The value of the property is
stored in the variable ``VAR``. If the property is not found, ``VAR``
will be set to "NOTFOUND". Use :command:`set_source_files_properties`
to set property values. Source file properties usually control how the
file is built. One property that is always there is :prop_sf:`LOCATION`
stored in the variable ``VAR``. If the source property is not found, the
behavior depends on whether it has been defined to be an ``INHERITED`` property
or not (see :command:`define_property`). Non-inherited properties will set
``VAR`` to "NOTFOUND", whereas inheritied properties will search the relevent
parent scope as described for the :command:`define_property` command and
if still unable to find the property, ``VAR`` will be set to an empty string.
Use :command:`set_source_files_properties` to set property values. Source
file properties usually control how the file is built. One property that is
always there is :prop_sf:`LOCATION`.
See also the more general :command:`get_property` command.

View File

@@ -8,8 +8,15 @@ Get a property from a target.
get_target_property(VAR target property)
Get a property from a target. The value of the property is stored in
the variable ``VAR``. If the property is not found, ``VAR`` will be set to
"NOTFOUND". Use :command:`set_target_properties` to set property values.
the variable ``VAR``. If the target property is not found, the behavior
depends on whether it has been defined to be an ``INHERITED`` property
or not (see :command:`define_property`). Non-inherited properties will
set ``VAR`` to "NOTFOUND", whereas inheritied properties will search the
relevent parent scope as described for the :command:`define_property`
command and if still unable to find the property, ``VAR`` will be set to
an empty string.
Use :command:`set_target_properties` to set target property values.
Properties are usually used to control how a target is built, but some
query the target instead. This command can get properties for any
target so far created. The targets do not need to be in the current

View File

@@ -8,8 +8,14 @@ Get a property of the test.
get_test_property(test property VAR)
Get a property from the test. The value of the property is stored in
the variable ``VAR``. If the test or property is not found, ``VAR`` will
be set to "NOTFOUND". For a list of standard properties you can type
``cmake --help-property-list``.
the variable ``VAR``. If the test property is not found, the behavior
depends on whether it has been defined to be an ``INHERITED`` property
or not (see :command:`define_property`). Non-inherited properties will
set ``VAR`` to "NOTFOUND", whereas inheritied properties will search the
relevent parent scope as described for the :command:`define_property`
command and if still unable to find the property, ``VAR`` will be set to
an empty string.
For a list of standard properties you can type ``cmake --help-property-list``.
See also the more general :command:`get_property` command.

View File

@@ -59,11 +59,17 @@ be one of the following:
The required ``PROPERTY`` option is immediately followed by the name of
the property to set. Remaining arguments are used to compose the
property value in the form of a semicolon-separated list. If the
``APPEND`` option is given the list is appended to any existing property
value. If the ``APPEND_STRING`` option is given the string is append to any
existing property value as string, i.e. it results in a longer string
and not a list of strings.
property value in the form of a semicolon-separated list.
If the ``APPEND`` option is given the list is appended to any existing
property value. If the ``APPEND_STRING`` option is given the string is
appended to any existing property value as string, i.e. it results in a
longer string and not a list of strings. When using ``APPEND`` or
``APPEND_STRING`` with a property defined to support ``INHERITED``
behavior (see :command:`define_property`), no inheriting occurs when
finding the initial value to append to. If the property is not already
directly set in the nominated scope, the command will behave as though
``APPEND`` or ``APPEND_STRING`` had not been given.
See the :manual:`cmake-properties(7)` manual for a list of properties
in each scope.