Merge topic 'source_file_scopes'

3d4b70ea64 set_source_files_properties: Allow specification of directory scope

Acked-by: Kitware Robot <kwrobot@kitware.com>
Merge-request: !4661

5 files changed, 59 insertions, 3 deletions

diff --git a/Help/command/get_property.rst b/Help/command/get_property.rst
index c0f9b46..80d97fd 100644
--- a/Help/command/get_property.rst
+++ b/Help/command/get_property.rst
@@ -10,6 +10,7 @@ Get a property.
                 DIRECTORY [<dir>]  |
                 TARGET    <target> |
                 SOURCE    <source> |
+                          [<TARGET_DIRECTORY ... | DIRECTORY ...>]   |
                 INSTALL   <file>   |
                 TEST      <test>   |
                 CACHE     <entry>  |
@@ -49,6 +50,15 @@ 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 decec19..893a1b6 100644
--- a/Help/command/get_source_file_property.rst
+++ b/Help/command/get_source_file_property.rst
@@ -5,7 +5,7 @@ Get a property for a source file.
 
 .. code-block:: cmake
 
-  get_source_file_property(VAR file property)
+  get_source_file_property(VAR file [<TARGET_DIRECTORY ... | DIRECTORY ...>] 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
@@ -15,6 +15,15 @@ or not (see :command:`define_property`).  Non-inherited properties will set
 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.
+
 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`.
diff --git a/Help/command/set_property.rst b/Help/command/set_property.rst
index 1728c98..de28be3 100644
--- a/Help/command/set_property.rst
+++ b/Help/command/set_property.rst
@@ -8,7 +8,8 @@ Set a named property in a given scope.
   set_property(<GLOBAL                      |
                 DIRECTORY [<dir>]           |
                 TARGET    [<target1> ...]   |
-                SOURCE    [<src1> ...]      |
+                SOURCE    [<src1> ...]
+                          [<TARGET_DIRECTORY ... | DIRECTORY ...>]   |
                 INSTALL   [<file1> ...]     |
                 TEST      [<test1> ...]     |
                 CACHE     [<entry1> ...]    >
@@ -34,8 +35,16 @@ It must be one of the following:
 
 ``SOURCE``
   Scope may name zero or more source files.  Note that source
-  file properties are visible only to targets added in the same
+  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 of the additional options: ``TARGET_DIRECTORY`` or ``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.
   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 ab95d70..8adfb9e 100644
--- a/Help/command/set_source_files_properties.rst
+++ b/Help/command/set_source_files_properties.rst
@@ -6,12 +6,25 @@ Source files can have properties that affect how they are built.
 .. code-block:: cmake
 
   set_source_files_properties([file1 [file2 [...]]]
+                              [<TARGET_DIRECTORY ... | DIRECTORY ...>]
                               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``).
+
+The file properties can be made visible in a different directory by specifying
+one of the additional options: ``TARGET_DIRECTORY`` or ``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.
+
 See also the :command:`set_property(SOURCE)` command.
 
 See :ref:`Source File Properties` for the list of properties known
diff --git a/Help/release/dev/sf-property-scopes.rst b/Help/release/dev/sf-property-scopes.rst
new file mode 100644
index 0000000..0b61625
--- /dev/null
+++ b/Help/release/dev/sf-property-scopes.rst
@@ -0,0 +1,15 @@
+sf-property-scopes
+------------------
+
+* The :command:`set_property` with the ``SOURCE`` scope gained the
+  ``DIRECTORY`` and ``TARGET_DIRECTORY`` options to set properties
+  in the provided directory scopes.
+* The :command:`set_source_files_properties` gained the ``DIRECTORY``
+  and ``TARGET_DIRECTORY`` options to set properties in the provided
+  directory scopes.
+* The :command:`get_property` with ``SOURCE`` scope gained the
+  ``DIRECTORY`` and ``TARGET_DIRECTORY`` options to get a property
+  from the provided directory scope.
+* The :command:`get_source_file_property` gained the ``DIRECTORY``
+  and ``TARGET_DIRECTORY`` options to get a property from the
+  provided directory scope.