target_sources: Interpret relative paths as relative to the calling directory

Previously the command considered non-absolute source file paths relative to
the associated target on the LHS. This causes problems in incremental builds
where files are added from subdirectories and forces users to workaround by
manually converting to absolute paths. Change this to enable more intuitive
usage by projects.

Fixes #17981

4 files changed, 48 insertions, 1 deletions

diff --git a/Help/command/target_sources.rst b/Help/command/target_sources.rst
index a4f5196..5dd8d86 100644
--- a/Help/command/target_sources.rst
+++ b/Help/command/target_sources.rst
@@ -9,7 +9,9 @@ Add sources to a target.
     <INTERFACE|PUBLIC|PRIVATE> [items1...]
     [<INTERFACE|PUBLIC|PRIVATE> [items2...] ...])
 
-Specify sources to use when compiling a given target.  The
+Specify sources to use when compiling a given target.  Relative
+source file paths are interpreted as being relative to the current
+source directory (i.e. :variable:`CMAKE_CURRENT_SOURCE_DIR`).  The
 named ``<target>`` must have been created by a command such as
 :command:`add_executable` or :command:`add_library` and must not be an
 :ref:`ALIAS target <Alias Targets>`.
@@ -27,3 +29,6 @@ Arguments to ``target_sources`` may use "generator expressions"
 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.
+
+See also the :policy:`CMP0076` policy for older behavior related to the
+handling of relative source file paths.
diff --git a/Help/manual/cmake-policies.7.rst b/Help/manual/cmake-policies.7.rst
index 631f75b..6179a7c 100644
--- a/Help/manual/cmake-policies.7.rst
+++ b/Help/manual/cmake-policies.7.rst
@@ -51,6 +51,14 @@ The :variable:`CMAKE_MINIMUM_REQUIRED_VERSION` variable may also be used
 to determine whether to report an error on use of deprecated macros or
 functions.
 
+Policies Introduced by CMake 3.13
+=================================
+
+.. toctree::
+   :maxdepth: 1
+
+   CMP0076: target_sources() command converts relative paths to absolute. </policy/CMP0076>
+
 Policies Introduced by CMake 3.12
 =================================
 
diff --git a/Help/policy/CMP0076.rst b/Help/policy/CMP0076.rst
new file mode 100644
index 0000000..dd25f80
--- /dev/null
+++ b/Help/policy/CMP0076.rst
@@ -0,0 +1,26 @@
+CMP0076
+-------
+
+The :command:`target_sources` command converts relative paths to absolute.
+
+In CMake 3.13 and above, the :command:`target_sources` command now converts
+relative source file paths to absolute paths in the following cases:
+
+* Source files are added to the target's :prop_tgt:`INTERFACE_SOURCES`
+  property.
+* The target's :prop_tgt:`SOURCE_DIR` property differs from
+  :variable:`CMAKE_CURRENT_SOURCE_DIR`.
+
+A path that begins with a generator expression is always left unmodified.
+
+This policy provides compatibility with projects that have not been updated
+to expect this behavior.  The ``OLD`` behavior for this policy is to leave
+all relative source file paths unmodified.  The ``NEW`` behavior of this
+policy is to convert relative paths to absolute according to above rules.
+
+This policy was introduced in CMake version 3.13.  CMake version
+|release| warns when the policy is not set and uses ``OLD`` behavior.
+Use the :command:`cmake_policy` command to set it to ``OLD`` or ``NEW``
+explicitly.
+
+.. include:: DEPRECATED.txt
diff --git a/Help/release/dev/subdirectory-sources.rst b/Help/release/dev/subdirectory-sources.rst
new file mode 100644
index 0000000..880b321
--- /dev/null
+++ b/Help/release/dev/subdirectory-sources.rst
@@ -0,0 +1,8 @@
+subdirectory-sources
+--------------------
+
+* The :command:`target_sources` command now interprets relative source file
+  paths as relative to the current source directory.  This simplifies
+  incrementally building up a target's sources from subdirectories.  The
+  :policy:`CMP0076` policy was added to provide backward compatibility with
+  the old behavior where required.