Help: Clarify relative path handling for target_include_directories()

Fixes: #22853

2 files changed, 20 insertions, 11 deletions

diff --git a/Help/command/target_include_directories.rst b/Help/command/target_include_directories.rst
index 3e53b2e4a1..3fc7926be5 100644
--- a/Help/command/target_include_directories.rst
+++ b/Help/command/target_include_directories.rst
@@ -27,9 +27,8 @@ The following arguments specify include directories.
 .. versionadded:: 3.11
   Allow setting ``INTERFACE`` items on :ref:`IMPORTED targets <Imported Targets>`.
 
-Specified include directories may be absolute paths or relative paths.
-Repeated calls for the same <target> append items in the order called.  If
-``SYSTEM`` is specified, the compiler will be told the
+Repeated calls for the same ``<target>`` append items in the order called.
+If ``SYSTEM`` is specified, the compiler will be told the
 directories are meant as system include directories on some platforms
 (signalling this setting might achieve effects such as the compiler
 skipping warnings, or these fixed-install system files not being
@@ -43,12 +42,22 @@ with the syntax ``$<...>``.  See the :manual:`cmake-generator-expressions(7)`
 manual for available expressions.  See the :manual:`cmake-buildsystem(7)`
 manual for more on defining buildsystem properties.
 
+Specified include directories may be absolute paths or relative paths.
+A relative path will be interpreted as relative to the current source
+directory (i.e. :variable:`CMAKE_CURRENT_SOURCE_DIR`) and converted to an
+absolute path before storing it in the associated target property.
+If the path starts with a generator expression, it will always be assumed
+to be an absolute path (with one exception noted below) and will be used
+unmodified.
+
 Include directories usage requirements commonly differ between the build-tree
-and the install-tree.  The ``BUILD_INTERFACE`` and ``INSTALL_INTERFACE``
-generator expressions can be used to describe separate usage requirements
-based on the usage location.  Relative paths are allowed within the
-``INSTALL_INTERFACE`` expression and are interpreted relative to the
-installation prefix.  For example:
+and the install-tree.  The :genex:`BUILD_INTERFACE` and
+:genex:`INSTALL_INTERFACE` generator expressions can be used to describe
+separate usage requirements based on the usage location.  Relative paths
+are allowed within the :genex:`INSTALL_INTERFACE` expression and are
+interpreted as relative to the installation prefix.  Relative paths should not
+be used in :genex:`BUILD_INTERFACE` expressions because they will not be
+converted to absolute.  For example:
 
 .. code-block:: cmake
 
diff --git a/Help/include/INTERFACE_INCLUDE_DIRECTORIES_WARNING.txt b/Help/include/INTERFACE_INCLUDE_DIRECTORIES_WARNING.txt
index a54d7280db..73e19079f8 100644
--- a/Help/include/INTERFACE_INCLUDE_DIRECTORIES_WARNING.txt
+++ b/Help/include/INTERFACE_INCLUDE_DIRECTORIES_WARNING.txt
@@ -1,11 +1,11 @@
 
-Note that it is not advisable to populate the ``INSTALL_INTERFACE`` of the
-|INTERFACE_PROPERTY_LINK| of a target with absolute paths to the include
+Note that it is not advisable to populate the :genex:`INSTALL_INTERFACE` of
+the |INTERFACE_PROPERTY_LINK| of a target with absolute paths to the include
 directories of dependencies.  That would hard-code into installed packages
 the include directory paths for dependencies
 **as found on the machine the package was made on**.
 
-The ``INSTALL_INTERFACE`` of the |INTERFACE_PROPERTY_LINK| is only
+The :genex:`INSTALL_INTERFACE` of the |INTERFACE_PROPERTY_LINK| is only
 suitable for specifying the required include directories for headers
 provided with the target itself, not those provided by the transitive
 dependencies listed in its :prop_tgt:`INTERFACE_LINK_LIBRARIES` target