set_source_files_properties: Allow specification of directory scope

Both set_source_files_properties() and set_property(SOURCE) now accept
two new optional arguments: DIRECTORY and TARGET_DIRECTORY.

The DIRECTORY option takes a list of relative or absolute paths
pointing to processed source directories (add_subdirectory was
already called on them).

These paths specify directory scopes where the source file properties
will be set. Previously the scope was always the currently processed
source directory.

Similarly TARGET_DIRECTORY takes a list of targets, whose source
directories will be used as the list of scopes where to set the
source file properties.

get_property() and get_source_file_property() also get the same
new arguments, except only one value can be specified instead
of a list.

Fixes: #20128

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.