{get,set}_property: Add support for referencing binary directories

Index directories by their binary directory path in addition to their
source directory path.

Fixes: #19262

4 files changed, 28 insertions, 9 deletions

diff --git a/Help/command/get_directory_property.rst b/Help/command/get_directory_property.rst
index 218efa9..39015cc 100644
--- a/Help/command/get_directory_property.rst
+++ b/Help/command/get_directory_property.rst
@@ -8,9 +8,14 @@ Get a property of ``DIRECTORY`` scope.
   get_directory_property(<variable> [DIRECTORY <dir>] <prop-name>)
 
 Stores a property of directory scope in the named ``<variable>``.
+
 The ``DIRECTORY`` argument specifies another directory from which
 to retrieve the property value instead of the current directory.
-The specified directory must have already been traversed by CMake.
+It may reference either a source directory, or since CMake 3.19,
+a binary directory.  Relative paths are treated as relative to the
+current source directory.  CMake must already know about the directory,
+either by having added it through a call to :command:`add_subdirectory`
+or being the top level directory.
 
 If the property is not defined for the nominated directory scope,
 an empty string is returned.  In the case of ``INHERITED`` properties,
diff --git a/Help/command/get_property.rst b/Help/command/get_property.rst
index 0602518..870c934 100644
--- a/Help/command/get_property.rst
+++ b/Help/command/get_property.rst
@@ -30,7 +30,9 @@ It must be one of the following:
 ``DIRECTORY``
   Scope defaults to the current directory but another
   directory (already processed by CMake) may be named by the
-  full or relative path ``<dir>``.
+  full or relative path ``<dir>``.  The ``<dir>`` may reference either a
+  source directory, or since CMake 3.19, a binary directory.
+  Relative paths are treated as relative to the current source directory.
   See also the :command:`get_directory_property` command.
 
 ``TARGET``
@@ -44,10 +46,11 @@ It must be one of the following:
 
   ``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.
+    scope.  The ``<dir>`` may reference either a source directory, or
+    since CMake 3.19, a binary directory.  CMake must already know about
+    the directory, either by having added it through a call
+    to :command:`add_subdirectory` or ``<dir>`` being the top level 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
diff --git a/Help/command/set_property.rst b/Help/command/set_property.rst
index 93c2d9c..b5c1613 100644
--- a/Help/command/set_property.rst
+++ b/Help/command/set_property.rst
@@ -26,8 +26,11 @@ It must be one of the following:
   Scope is unique and does not accept a name.
 
 ``DIRECTORY``
-  Scope defaults to the current directory but another directory
+  Scope defaults to the current directory but other directories
   (already processed by CMake) may be named by full or relative path.
+  Each path may reference either a source directory, or since CMake 3.19,
+  a binary directory.
+  Relative paths are treated as relative to the current source directory.
   See also the :command:`set_directory_properties` command.
 
 ``TARGET``
@@ -42,8 +45,9 @@ It must be one of the following:
 
   ``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
+    directories' scopes.  Each path may reference either a source directory,
+    or since CMake 3.19, a binary directory.  CMake must already know about
+    each of these 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.
 
diff --git a/Help/release/dev/binary-dir-props.rst b/Help/release/dev/binary-dir-props.rst
new file mode 100644
index 0000000..b36d86d
--- /dev/null
+++ b/Help/release/dev/binary-dir-props.rst
@@ -0,0 +1,7 @@
+binary-dir-props
+----------------
+
+* The :command:`set_property`, :command:`get_property`,
+  and :command:`get_directory_property` commands' ``DIRECTORY``
+  options now accept references to binary directory paths,
+  such as the value of :variable:`CMAKE_CURRENT_BINARY_DIR`.