Commit 1ec3fee1 authored by Brad King's avatar Brad King Committed by Kitware Robot
Browse files

Merge topic 'doc-source-prop-dir-options' into release-3.18

0bdb1a77

 Help: Clarify wording of dir-related source property options
Acked-by: Kitware Robot's avatarKitware Robot <kwrobot@kitware.com>
Merge-request: !5000
parents aedc5e19 0bdb1a77
......@@ -10,7 +10,7 @@ Get a property.
DIRECTORY [<dir>] |
TARGET <target> |
SOURCE <source> |
[TARGET_DIRECTORY <target> | DIRECTORY <dir>] |
[DIRECTORY <dir> | TARGET_DIRECTORY <target>] |
INSTALL <file> |
TEST <test> |
CACHE <entry> |
......@@ -31,18 +31,36 @@ It must be one of the following:
Scope defaults to the current directory but another
directory (already processed by CMake) may be named by the
full or relative path ``<dir>``.
See also the :command:`get_directory_property` command.
``TARGET``
Scope must name one existing target.
See also the :command:`get_target_property` command.
``SOURCE``
Scope must name one source file.
Scope must name one source file. By default, the source file's property
will be read from the current source directory's scope, but this can be
overridden with one of the following sub-options:
``DIRECTORY <dir>``
The source file property will be read from the ``<dir>`` directory's
scope. CMake must already know about that source directory, either by
having added it through a call to :command:`add_subdirectory` or ``<dir>``
being the top level source directory. Relative paths are treated as
relative to the current source directory.
``TARGET_DIRECTORY <target>``
The source file property will be read from the directory scope in which
``<target>`` was created (``<target>`` must therefore already exist).
See also the :command:`get_source_file_property` command.
``INSTALL``
Scope must name one installed file path.
``TEST``
Scope must name one existing test.
See also the :command:`get_test_property` command.
``CACHE``
Scope must name one cache entry.
......@@ -50,15 +68,6 @@ It must be one of the following:
``VARIABLE``
Scope is unique and does not accept a name.
In the ``SOURCE`` case, the queried source file scope can be changed by
specifying one of the additional options: ``DIRECTORY`` or ``TARGET_DIRECTORY``.
``DIRECTORY`` takes a path to a processed directory, and the source file property
will be read from that directory scope.
``TARGET_DIRECTORY`` takes the name of an existing target. The source file
property will be read from this target's directory scope.
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, although some properties support inheriting from a parent scope
......
......@@ -5,24 +5,33 @@ Get a property for a source file.
.. code-block:: cmake
get_source_file_property(VAR file [TARGET_DIRECTORY <target> | DIRECTORY <dir>] property)
get_source_file_property(<variable> <file>
[DIRECTORY <dir> | TARGET_DIRECTORY <target>]
<property>)
Gets a property from a source file. The value of the property is
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 inherited properties will search the relevant
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.
The queried source file scope can be changed by specifying one of the
additional options: ``DIRECTORY`` or ``TARGET_DIRECTORY``.
``DIRECTORY`` takes a path to a processed directory, and the source file property
will be read from that directory scope.
``TARGET_DIRECTORY`` takes the name of an existing target. The source file
property will be read from this target's directory scope.
stored in the specified ``<variable>``. 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 ``variable`` to ``NOTFOUND``, whereas inherited properties will search
the relevant parent scope as described for the :command:`define_property`
command and if still unable to find the property, ``variable`` will be set to
an empty string.
By default, the source file's property will be read from the current source
directory's scope, but this can be overridden with one of the following
sub-options:
``DIRECTORY <dir>``
The source file property will be read from the ``<dir>`` directory's
scope. CMake must already know about that source directory, either by
having added it through a call to :command:`add_subdirectory` or ``<dir>``
being the top level source directory. Relative paths are treated as
relative to the current source directory.
``TARGET_DIRECTORY <target>``
The source file property will be read from the directory scope in which
``<target>`` was created (``<target>`` must therefore already exist).
Use :command:`set_source_files_properties` to set property values. Source
file properties usually control how the file is built. One property that is
......
......@@ -9,13 +9,13 @@ Set a named property in a given scope.
DIRECTORY [<dir>] |
TARGET [<target1> ...] |
SOURCE [<src1> ...]
[TARGET_DIRECTORY <target1> ...]
[DIRECTORY <dir1> ...] |
[DIRECTORY <dirs> ...] |
[TARGET_DIRECTORY <targets> ...]
INSTALL [<file1> ...] |
TEST [<test1> ...] |
CACHE [<entry1> ...] >
[APPEND] [APPEND_STRING]
PROPERTY <name> [value1 ...])
PROPERTY <name> [<value1> ...])
Sets one property on zero or more objects of a scope.
......@@ -35,17 +35,23 @@ It must be one of the following:
See also the :command:`set_target_properties` command.
``SOURCE``
Scope may name zero or more source files. Note that source
file properties are by default visible only to targets added in the same
directory (``CMakeLists.txt``).
The file properties can be made visible in a different directory by specifying
one or both of the additional options: ``TARGET_DIRECTORY`` and ``DIRECTORY``.
Scope may name zero or more source files. By default, source file properties
are only visible to targets added in the same directory (``CMakeLists.txt``).
Visibility can be set in other directory scopes using one or both of the
following sub-options:
``DIRECTORY <dirs>...``
The source file property will be set in each of the ``<dirs>``
directories' scopes. CMake must already know about each of these
source directories, either by having added them through a call to
:command:`add_subdirectory` or it being the top level source directory.
Relative paths are treated as relative to the current source directory.
``TARGET_DIRECTORY <targets>...``
The source file property will be set in each of the directory scopes
where any of the specified ``<targets>`` were created (the ``<targets>``
must therefore already exist).
``DIRECTORY`` takes a list of processed directories paths, and sets the file
properties in those directory scopes.
``TARGET_DIRECTORY`` takes a list of existing targets. The file
properties will be set in these targets' directory scopes.
See also the :command:`set_source_files_properties` command.
``INSTALL``
......
......@@ -5,29 +5,33 @@ Source files can have properties that affect how they are built.
.. code-block:: cmake
set_source_files_properties([file1 [file2 [...]]]
[TARGET_DIRECTORY <target1> ...]
[DIRECTORY <dir1> ...]
PROPERTIES prop1 value1
[prop2 value2 [...]])
set_source_files_properties(<files> ...
[DIRECTORY <dirs> ...]
[TARGET_DIRECTORY <targets> ...]
PROPERTIES <prop1> <value1>
[<prop2> <value2>] ...)
Sets properties associated with source files using a key/value paired
list.
Note that source file properties are by default visible only to
targets added in the same directory (``CMakeLists.txt``).
By default, source file properties are only visible to targets added in the
same directory (``CMakeLists.txt``). Visibility can be set in other directory
scopes using one or both of the following options:
The file properties can be made visible in a different directory by specifying
one or both of the additional options: ``TARGET_DIRECTORY`` and ``DIRECTORY``.
``DIRECTORY <dirs>...``
The source file properties will be set in each of the ``<dirs>``
directories' scopes. CMake must already know about each of these
source directories, either by having added them through a call to
:command:`add_subdirectory` or it being the top level source directory.
Relative paths are treated as relative to the current source directory.
``DIRECTORY`` takes a list of processed directories paths, and sets the file
properties in those directory scopes.
``TARGET_DIRECTORY`` takes a list of existing targets. The file
properties will be set in these targets' directory scopes.
``TARGET_DIRECTORY <targets>...``
The source file properties will be set in each of the directory scopes
where any of the specified ``<targets>`` were created (the ``<targets>``
must therefore already exist).
Use :command:`get_source_file_property` to get property values.
See also the :command:`set_property(SOURCE)` command.
See :ref:`Source File Properties` for the list of properties known
to CMake. Source file properties are visible only to targets added
in the same directory (``CMakeLists.txt``).
to CMake.
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment