LINK_DIRECTORIES: Add new properties and commands

These new capabilities enable to manage link directories

Two new properties:
* target properties: LINK_DIRECTORIES and INTERFACE_LINK_DIRECTORIES

One new command
* target_link_directories(): to populate target properties

Fixes: #17215

Help/command/link_directories.rst

@@ -1,19 +1,45 @@
 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(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.
+
+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.

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