mirror/CMake
1
0
Fork 0
mirror of https://github.com/Kitware/CMake.git synced 2025-12-31 19:00:54 -06:00
Code Issues Packages Projects Releases Wiki Activity

Help: Clarify wording of dir-related source property options

Browse Source
This commit is contained in:
Craig Scott
2020-07-11 19:10:00 +10:00
parent 6ab08c4e99
commit 0bdb1a77d1
4 changed files with 80 additions and 52 deletions
Download Patch File Download Diff File Expand all files Collapse all files

31
Help/command/get_property.rst
View File

@@ -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

35
Help/command/get_source_file_property.rst
View File

@@ -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.
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.
The queried source file scope can be changed by specifying one of the
additional options: ``DIRECTORY`` or ``TARGET_DIRECTORY``.
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`` takes a path to a processed directory, and the source file property
will be read from that directory scope.
``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`` takes the name of an existing target. The source file
property will be read from this target's directory scope.
``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

30
Help/command/set_property.rst
View File

@@ -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`` takes a list of processed directories paths, and sets the file
properties in those directory scopes.
``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).
``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``

36
Help/command/set_source_files_properties.rst
View File

@@ -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.