Merge topic 'link-directories'

f9717725f9 link_directories(): enhance capabilities
b5915744eb LINK_DIRECTORIES target property: add policy for absolute paths check.
a71caab46b LINK_DIRECTORIES: Add new properties and commands
5ca130e223 Refactoring: introduce function to check if a string is a generator expression

Acked-by: Kitware Robot <kwrobot@kitware.com>
Merge-request: !2403

14 files changed, 190 insertions, 12 deletions

diff --git a/Help/command/link_directories.rst b/Help/command/link_directories.rst
index 5c64bc6..1dce9a0 100644
--- a/Help/command/link_directories.rst
+++ b/Help/command/link_directories.rst
@@ -1,19 +1,51 @@
 link_directories
 ----------------
 
-Specify directories in which the linker will look for libraries.
+Add directories in which the linker will look for libraries.
 
 ::
 
-  link_directories(directory1 directory2 ...)
+  link_directories([AFTER|BEFORE] directory1 [directory2 ...])
 
-Specify the paths in which the linker should search for libraries.
-The command will apply only to targets created after it is called.
+Add the paths in which the linker should search for libraries.
 Relative paths given to this command are interpreted as relative to
 the current source directory, see :policy:`CMP0015`.
 
-Note that this command is rarely necessary.  Library locations
-returned by :command:`find_package` and :command:`find_library` are
-absolute paths. Pass these absolute library file paths directly to the
-:command:`target_link_libraries` command.  CMake will ensure the linker finds
-them.
+The directories are added to the :prop_dir:`LINK_DIRECTORIES` directory
+property for the current ``CMakeLists.txt`` file, converting relative
+paths to absolute as needed.
+The command will apply only to targets created after it is called.
+
+By default the directories specified are appended onto the current list of
+directories.  This default behavior can be changed by setting
+:variable:`CMAKE_LINK_DIRECTORIES_BEFORE` to ``ON``.  By using
+``AFTER`` or ``BEFORE`` explicitly, you can select between appending and
+prepending, independent of the default.
+
+Arguments to ``link_directories`` 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.
+
+.. note::
+
+  This command is rarely necessary and should be avoided where there are
+  other choices.  Prefer to pass full absolute paths to libraries where
+  possible, since this ensures the correct library will always be linked.
+  The :command:`find_library` command provides the full path, which can
+  generally be used directly in calls to :command:`target_link_libraries`.
+  Situations where a library search path may be needed include:
+
+  - Project generators like Xcode where the user can switch target
+    architecture at build time, but a full path to a library cannot
+    be used because it only provides one architecture (i.e. it is not
+    a universal binary).
+  - Libraries may themselves have other private library dependencies
+    that expect to be found via ``RPATH`` mechanisms, but some linkers
+    are not able to fully decode those paths (e.g. due to the presence
+    of things like ``$ORIGIN``).
+
+  If a library search path must be provided, prefer to localize the effect
+  where possible by using the :command:`target_link_directories` command
+  rather than ``link_directories()``.  The target-specific command can also
+  control how the search directories propagate to other dependent targets.
diff --git a/Help/command/target_link_directories.rst b/Help/command/target_link_directories.rst
new file mode 100644
index 0000000..b46aac0
--- /dev/null
+++ b/Help/command/target_link_directories.rst
@@ -0,0 +1,55 @@
+target_link_directories
+-----------------------
+
+Add link directories to a target.
+
+::
+
+  target_link_directories(<target> [BEFORE]
+    <INTERFACE|PUBLIC|PRIVATE> [items1...]
+    [<INTERFACE|PUBLIC|PRIVATE> [items2...] ...])
+
+Specify the paths in which the linker should search for libraries when
+linking a given target.  Each item can be an absolute or relative path,
+with the latter being interpreted as relative to the current source
+directory.  These items will be added to the link command.
+
+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>`.
+
+The ``INTERFACE``, ``PUBLIC`` and ``PRIVATE`` keywords are required to
+specify the scope of the items that follow them.  ``PRIVATE`` and
+``PUBLIC`` items will populate the :prop_tgt:`LINK_DIRECTORIES` property
+of ``<target>``.  ``PUBLIC`` and ``INTERFACE`` items will populate the
+:prop_tgt:`INTERFACE_LINK_DIRECTORIES` property of ``<target>``
+(:ref:`IMPORTED targets <Imported Targets>` only support ``INTERFACE`` items).
+Each item specifies a link directory and will be converted to an absolute
+path if necessary before adding it to the relevant property.  Repeated
+calls for the same ``<target>`` append items in the order called.
+
+If ``BEFORE`` is specified, the content will be prepended to the relevant
+property instead of being appended.
+
+Arguments to ``target_link_directories`` 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.
+
+.. note::
+
+  This command is rarely necessary and should be avoided where there are
+  other choices.  Prefer to pass full absolute paths to libraries where
+  possible, since this ensures the correct library will always be linked.
+  The :command:`find_library` command provides the full path, which can
+  generally be used directly in calls to :command:`target_link_libraries`.
+  Situations where a library search path may be needed include:
+
+  - Project generators like Xcode where the user can switch target
+    architecture at build time, but a full path to a library cannot
+    be used because it only provides one architecture (i.e. it is not
+    a universal binary).
+  - Libraries may themselves have other private library dependencies
+    that expect to be found via ``RPATH`` mechanisms, but some linkers
+    are not able to fully decode those paths (e.g. due to the presence
+    of things like ``$ORIGIN``).
diff --git a/Help/manual/cmake-commands.7.rst b/Help/manual/cmake-commands.7.rst
index 753647d..0cc5fca 100644
--- a/Help/manual/cmake-commands.7.rst
+++ b/Help/manual/cmake-commands.7.rst
@@ -111,6 +111,7 @@ These commands are available only in CMake projects.
    /command/target_compile_features
    /command/target_compile_options
    /command/target_include_directories
+   /command/target_link_directories
    /command/target_link_libraries
    /command/target_link_options
    /command/target_sources
diff --git a/Help/manual/cmake-policies.7.rst b/Help/manual/cmake-policies.7.rst
index 904ebee..2cc52fe 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
 
+   CMP0081: Relative paths not allowed in LINK_DIRECTORIES target property. </policy/CMP0081>
    CMP0080: BundleUtilities cannot be included at configure time. </policy/CMP0080>
    CMP0079: target_link_libraries allows use with targets in other directories. </policy/CMP0079>
    CMP0078: UseSWIG generates standard target names. </policy/CMP0078>
diff --git a/Help/manual/cmake-properties.7.rst b/Help/manual/cmake-properties.7.rst
index 8ccd7f6..5c3eb81 100644
--- a/Help/manual/cmake-properties.7.rst
+++ b/Help/manual/cmake-properties.7.rst
@@ -228,6 +228,7 @@ Properties on Targets
    /prop_tgt/INTERFACE_COMPILE_OPTIONS
    /prop_tgt/INTERFACE_INCLUDE_DIRECTORIES
    /prop_tgt/INTERFACE_LINK_DEPENDS
+   /prop_tgt/INTERFACE_LINK_DIRECTORIES
    /prop_tgt/INTERFACE_LINK_LIBRARIES
    /prop_tgt/INTERFACE_LINK_OPTIONS
    /prop_tgt/INTERFACE_POSITION_INDEPENDENT_CODE
@@ -252,6 +253,7 @@ Properties on Targets
    /prop_tgt/LINK_DEPENDS_NO_SHARED
    /prop_tgt/LINK_DEPENDS
    /prop_tgt/LINKER_LANGUAGE
+   /prop_tgt/LINK_DIRECTORIES
    /prop_tgt/LINK_FLAGS_CONFIG
    /prop_tgt/LINK_FLAGS
    /prop_tgt/LINK_INTERFACE_LIBRARIES_CONFIG
diff --git a/Help/manual/cmake-variables.7.rst b/Help/manual/cmake-variables.7.rst
index 6071999..78353fb 100644
--- a/Help/manual/cmake-variables.7.rst
+++ b/Help/manual/cmake-variables.7.rst
@@ -179,6 +179,7 @@ Variables that Change Behavior
    /variable/CMAKE_INSTALL_PREFIX
    /variable/CMAKE_INSTALL_PREFIX_INITIALIZED_TO_DEFAULT
    /variable/CMAKE_LIBRARY_PATH
+   /variable/CMAKE_LINK_DIRECTORIES_BEFORE
    /variable/CMAKE_MFC_FLAG
    /variable/CMAKE_MODULE_PATH
    /variable/CMAKE_NOT_USING_CONFIG_FLAGS
diff --git a/Help/policy/CMP0081.rst b/Help/policy/CMP0081.rst
new file mode 100644
index 0000000..d3b2872
--- /dev/null
+++ b/Help/policy/CMP0081.rst
@@ -0,0 +1,22 @@
+CMP0081
+-------
+
+Relative paths not allowed in :prop_tgt:`LINK_DIRECTORIES` target property.
+
+CMake 3.12 and lower allowed the :prop_dir:`LINK_DIRECTORIES` directory
+property to contain relative paths.  The base path for such relative
+entries is not well defined.  CMake 3.13 and later will issue a
+``FATAL_ERROR`` if the :prop_tgt:`LINK_DIRECTORIES` target property
+(which is initialized by the :prop_dir:`LINK_DIRECTORIES` directory property)
+contains a relative path.
+
+The ``OLD`` behavior for this policy is not to warn about relative paths
+in the :prop_tgt:`LINK_DIRECTORIES` target property.  The ``NEW`` behavior for
+this policy is to issue a ``FATAL_ERROR`` if :prop_tgt:`LINK_DIRECTORIES`
+contains a relative path.
+
+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_dir/LINK_DIRECTORIES.rst b/Help/prop_dir/LINK_DIRECTORIES.rst
index fa37576..f9fb815 100644
--- a/Help/prop_dir/LINK_DIRECTORIES.rst
+++ b/Help/prop_dir/LINK_DIRECTORIES.rst
@@ -3,6 +3,15 @@ LINK_DIRECTORIES
 
 List of linker search directories.
 
-This read-only property specifies the list of directories given so far
-to the link_directories command.  It is intended for debugging
-purposes.
+This property holds a :ref:`;-list <CMake Language Lists>` of directories
+and is typically populated using the :command:`link_directories` command.
+It gets its initial value from its parent directory, if it has one.
+
+The directory property is used to initialize the :prop_tgt:`LINK_DIRECTORIES`
+target property when a target is created.  That target property is used
+by the generators to set the library search directories for the linker.
+
+Contents of ``LINK_DIRECTORIES`` 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.
diff --git a/Help/prop_tgt/INTERFACE_LINK_DIRECTORIES.rst b/Help/prop_tgt/INTERFACE_LINK_DIRECTORIES.rst
new file mode 100644
index 0000000..56a4ec0
--- /dev/null
+++ b/Help/prop_tgt/INTERFACE_LINK_DIRECTORIES.rst
@@ -0,0 +1,9 @@
+INTERFACE_LINK_DIRECTORIES
+--------------------------
+
+.. |property_name| replace:: link directories
+.. |command_name| replace:: :command:`target_link_directories`
+.. |PROPERTY_INTERFACE_NAME| replace:: ``INTERFACE_LINK_DIRECTORIES``
+.. |PROPERTY_LINK| replace:: :prop_tgt:`LINK_DIRECTORIES`
+.. |PROPERTY_GENEX| replace:: ``$<TARGET_PROPERTY:foo,INTERFACE_LINK_DIRECTORIES>``
+.. include:: INTERFACE_BUILD_PROPERTY.txt
diff --git a/Help/prop_tgt/LINK_DIRECTORIES.rst b/Help/prop_tgt/LINK_DIRECTORIES.rst
new file mode 100644
index 0000000..085a701
--- /dev/null
+++ b/Help/prop_tgt/LINK_DIRECTORIES.rst
@@ -0,0 +1,18 @@
+LINK_DIRECTORIES
+----------------
+
+List of directories to use for the link step of shared library, module
+and executable targets.
+
+This property holds a :ref:`;-list <CMake Language Lists>` of directories
+specified so far for its target.  Use the :command:`target_link_directories`
+command to append more search directories.
+
+This property is initialized by the :prop_dir:`LINK_DIRECTORIES` directory
+property when a target is created, and is used by the generators to set
+the search directories for the linker.
+
+Contents of ``LINK_DIRECTORIES`` 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.
diff --git a/Help/release/dev/LINK_DIRECTORIES-policy.rst b/Help/release/dev/LINK_DIRECTORIES-policy.rst
new file mode 100644
index 0000000..5bbfa51
--- /dev/null
+++ b/Help/release/dev/LINK_DIRECTORIES-policy.rst
@@ -0,0 +1,5 @@
+LINK_DIRECTORIES-policy
+-----------------------
+
+* The :prop_tgt:`LINK_DIRECTORIES` target property expects absolute paths.
+  See policy :policy:`CMP0081`.
diff --git a/Help/release/dev/LINK_DIRECTORIES.rst b/Help/release/dev/LINK_DIRECTORIES.rst
new file mode 100644
index 0000000..dc7d609
--- /dev/null
+++ b/Help/release/dev/LINK_DIRECTORIES.rst
@@ -0,0 +1,9 @@
+LINK_DIRECTORIES
+----------------
+
+* CMake gained new capabilities to manage link directories:
+
+  * :prop_tgt:`LINK_DIRECTORIES` and :prop_tgt:`INTERFACE_LINK_DIRECTORIES`
+    target properties.
+  * :command:`target_link_directories` command to add link directories to
+    targets.
diff --git a/Help/release/dev/link_directories-enhancements.rst b/Help/release/dev/link_directories-enhancements.rst
new file mode 100644
index 0000000..2521fa1
--- /dev/null
+++ b/Help/release/dev/link_directories-enhancements.rst
@@ -0,0 +1,5 @@
+link_directories-enhancements
+-----------------------------
+
+* :command:`link_directories` command gains capability to control directories
+  insertion position.
diff --git a/Help/variable/CMAKE_LINK_DIRECTORIES_BEFORE.rst b/Help/variable/CMAKE_LINK_DIRECTORIES_BEFORE.rst
new file mode 100644
index 0000000..026ca35
--- /dev/null
+++ b/Help/variable/CMAKE_LINK_DIRECTORIES_BEFORE.rst
@@ -0,0 +1,9 @@
+CMAKE_LINK_DIRECTORIES_BEFORE
+-----------------------------
+
+Whether to append or prepend directories by default in
+:command:`link_directories`.
+
+This variable affects the default behavior of the :command:`link_directories`
+command.  Setting this variable to ``ON`` is equivalent to using the ``BEFORE``
+option in all uses of that command.