diff options
author | Brad King <brad.king@kitware.com> | 2020-07-13 11:51:53 (GMT) |
---|---|---|
committer | Kitware Robot <kwrobot@kitware.com> | 2020-07-13 11:52:01 (GMT) |
commit | 1ec3fee12b205ded5e3afc74a47d47e0dc870b03 (patch) | |
tree | b71ea9f9fddf9756608a66cf58092eecf9d2102a | |
parent | aedc5e19f34890192c955059f8d9b742784b4b79 (diff) | |
parent | 0bdb1a77d1ffe78da317c5fc724a8c4d8d5e0ae0 (diff) | |
download | CMake-1ec3fee12b205ded5e3afc74a47d47e0dc870b03.zip CMake-1ec3fee12b205ded5e3afc74a47d47e0dc870b03.tar.gz CMake-1ec3fee12b205ded5e3afc74a47d47e0dc870b03.tar.bz2 |
Merge topic 'doc-source-prop-dir-options' into release-3.18
0bdb1a77d1 Help: Clarify wording of dir-related source property options
Acked-by: Kitware Robot <kwrobot@kitware.com>
Merge-request: !5000
-rw-r--r-- | Help/command/get_property.rst | 31 | ||||
-rw-r--r-- | Help/command/get_source_file_property.rst | 41 | ||||
-rw-r--r-- | Help/command/set_property.rst | 32 | ||||
-rw-r--r-- | Help/command/set_source_files_properties.rst | 36 |
4 files changed, 84 insertions, 56 deletions
diff --git a/Help/command/get_property.rst b/Help/command/get_property.rst index 123cd45..0602518 100644 --- a/Help/command/get_property.rst +++ b/Help/command/get_property.rst @@ -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 diff --git a/Help/command/get_source_file_property.rst b/Help/command/get_source_file_property.rst index 1060251..76ed776 100644 --- a/Help/command/get_source_file_property.rst +++ b/Help/command/get_source_file_property.rst @@ -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 diff --git a/Help/command/set_property.rst b/Help/command/set_property.rst index ccbd635..93c2d9c 100644 --- a/Help/command/set_property.rst +++ b/Help/command/set_property.rst @@ -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`` diff --git a/Help/command/set_source_files_properties.rst b/Help/command/set_source_files_properties.rst index 59d5ba3..9558b40 100644 --- a/Help/command/set_source_files_properties.rst +++ b/Help/command/set_source_files_properties.rst @@ -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. |