Merge topic 'out-of-dir-linking'

a1ad0a699b target_link_libraries: Allow use with targets in other directories
9bbae5ae28 cmTarget: Future-proof AddLinkLibrary target lookup scope
f9cb6f618a cmExportFileGenerator: Use cmGeneratorTarget::ResolveTargetReference
18441a6269 cmGeneratorTarget: Factor target name resolution out of link item resolution
2f708f5d65 Make internal TARGET_PROPERTY generator expressions more robust
94a75801c8 Android.mk: De-duplicate link libraries logic during export
8a63b23d16 cmGlobalGenerator: Remove unused FindLocalGenerator method

Acked-by: Kitware Robot <kwrobot@kitware.com>
Reviewed-by: Patrick Stotko <stotko@cs.uni-bonn.de>
Merge-request: !2370

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`.