target_link_libraries: Allow use with targets in other directories

Previously the command did not allow naming targets on the LHS that
were not created in the calling directory.  Lift this restriction to
enable more flexible use by projects.

Targets named on the RHS will need to be looked up during generation in
the scope of the call site rather than the scope of the LHS target.
Introduce an internal syntax in `[INTERFACE_]LINK_LIBRARIES` properties
to specify target names that need to be looked up in a directory other
than that containing the target on which the property is set.  Add
minimal documentation of the syntax to help users that encounter it.

Unfortunately CMake previously did allow such calls in the case that
only `INTERFACE` libraries are specified, but those libraries would be
looked up in the target's directory rather than the caller's.  Add
policy `CMP0079` to enable the new behavior with new lookup scope in a
compatible way.

Fixes: #17943

7 files changed, 68 insertions, 4 deletions

diff --git a/Help/command/target_link_libraries.rst b/Help/command/target_link_libraries.rst
index 1f0d69e..e1c374e 100644
--- a/Help/command/target_link_libraries.rst
+++ b/Help/command/target_link_libraries.rst
@@ -18,10 +18,13 @@ All of them have the general form::
 
   target_link_libraries(<target> ... <item>... ...)
 
-The named ``<target>`` must have been created in the current directory by
-a command such as :command:`add_executable` or :command:`add_library` and
-must not be an :ref:`ALIAS target <Alias Targets>`.
-Repeated calls for the same ``<target>`` append items in the order called.
+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>`.  If policy :policy:`CMP0079` is not
+set to ``NEW`` then the target must have been created in the current
+directory.  Repeated calls for the same ``<target>`` append items in
+the order called.
+
 Each ``<item>`` may be:
 
 * **A library target name**: The generated link line will have the
diff --git a/Help/manual/cmake-policies.7.rst b/Help/manual/cmake-policies.7.rst
index 32a0118..8ecca4d 100644
--- a/Help/manual/cmake-policies.7.rst
+++ b/Help/manual/cmake-policies.7.rst
@@ -57,6 +57,7 @@ Policies Introduced by CMake 3.13
 .. toctree::
    :maxdepth: 1
 
+   CMP0079: target_link_libraries allows use with targets in other directories. </policy/CMP0079>
    CMP0078: UseSWIG generates standard target names. </policy/CMP0078>
    CMP0077: option() honors normal variables. </policy/CMP0077>
    CMP0076: target_sources() command converts relative paths to absolute. </policy/CMP0076>
diff --git a/Help/policy/CMP0079.rst b/Help/policy/CMP0079.rst
new file mode 100644
index 0000000..0244d6c
--- /dev/null
+++ b/Help/policy/CMP0079.rst
@@ -0,0 +1,40 @@
+CMP0079
+-------
+
+:command:`target_link_libraries` allows use with targets in other directories.
+
+Prior to CMake 3.13 the :command:`target_link_libraries` command did not
+accept targets not created in the calling directory as its first argument
+for calls that update the :prop_tgt:`LINK_LIBRARIES` of the target itself.
+It did accidentally accept targets from other directories on calls that
+only update the :prop_tgt:`INTERFACE_LINK_LIBRARIES`, but would simply
+add entries to the property as if the call were made in the original
+directory.  Thus link interface libraries specified this way were always
+looked up by generators in the scope of the original target rather than
+in the scope that called :command:`target_link_libraries`.
+
+CMake 3.13 now allows the :command:`target_link_libraries` command to
+be called from any directory to add link dependencies and link interface
+libraries to targets created in other directories.  The entries are added
+to :prop_tgt:`LINK_LIBRARIES` and :prop_tgt:`INTERFACE_LINK_LIBRARIES`
+using a special (internal) suffix to tell the generators to look up the
+names in the calling scope rather than the scope that created the target.
+
+This policy provides compatibility with projects that already use
+:command:`target_link_libraries` with the ``INTERFACE`` keyword
+on a target in another directory to add :prop_tgt:`INTERFACE_LINK_LIBRARIES`
+entries to be looked up in the target's directory.  Such projects should
+be updated to be aware of the new scoping rules in that case.
+
+The ``OLD`` behavior of this policy is to disallow
+:command:`target_link_libraries` calls naming targets from another directory
+except in the previously accidentally allowed case of using the ``INTERFACE``
+keyword only.  The ``NEW`` behavior of this policy is to allow all such
+calls but use the new scoping 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/prop_tgt/INTERFACE_LINK_LIBRARIES.rst b/Help/prop_tgt/INTERFACE_LINK_LIBRARIES.rst
index 832d12b..bf7f72f 100644
--- a/Help/prop_tgt/INTERFACE_LINK_LIBRARIES.rst
+++ b/Help/prop_tgt/INTERFACE_LINK_LIBRARIES.rst
@@ -17,6 +17,8 @@ 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.
 
+.. include:: LINK_LIBRARIES_INDIRECTION.txt
+
 Creating Relocatable Packages
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
diff --git a/Help/prop_tgt/LINK_LIBRARIES.rst b/Help/prop_tgt/LINK_LIBRARIES.rst
index aa4b9f5..d88e798 100644
--- a/Help/prop_tgt/LINK_LIBRARIES.rst
+++ b/Help/prop_tgt/LINK_LIBRARIES.rst
@@ -15,3 +15,5 @@ Contents of ``LINK_LIBRARIES`` 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.
+
+.. include:: LINK_LIBRARIES_INDIRECTION.txt
diff --git a/Help/prop_tgt/LINK_LIBRARIES_INDIRECTION.txt b/Help/prop_tgt/LINK_LIBRARIES_INDIRECTION.txt
new file mode 100644
index 0000000..1fdb6ad
--- /dev/null
+++ b/Help/prop_tgt/LINK_LIBRARIES_INDIRECTION.txt
@@ -0,0 +1,10 @@
+.. note::
+  A call to :command:`target_link_libraries(<target> ...)` may update this
+  property on ``<target>``.  If ``<target>`` was not created in the same
+  directory as the call then :command:`target_link_libraries` will add a
+  suffix of the form ``::@<directory-id>`` to each entry, where the
+  ``::@`` is a separator and the ``<directory-id>`` is unspecified.
+  This tells the generators that the named libraries must be looked up in
+  the scope of the caller rather than in the scope in which the
+  ``<target>`` was created.  Valid directory ids are stripped on export
+  by the :command:`install(EXPORT)` and :command:`export` commands.
diff --git a/Help/release/dev/out-of-dir-linking.rst b/Help/release/dev/out-of-dir-linking.rst
new file mode 100644
index 0000000..6166be6
--- /dev/null
+++ b/Help/release/dev/out-of-dir-linking.rst
@@ -0,0 +1,6 @@
+out-of-dir-linking
+------------------
+
+* The :command:`target_link_libraries` command may now be called
+  to modify targets created outside the current directory.
+  See policy :policy:`CMP0079`.