Help: Revise target_link_libraries command documentation

Organize the documentation into subsections to separate the signatures.
Refactor the discussion of allowed link items into bullet points and
expand into more detail on each.

1 files changed, 124 insertions, 84 deletions

diff --git a/Help/command/target_link_libraries.rst b/Help/command/target_link_libraries.rst
index 88a555aa4b..393c8b454e 100644
--- a/Help/command/target_link_libraries.rst
+++ b/Help/command/target_link_libraries.rst
@@ -1,38 +1,107 @@
 target_link_libraries
 ---------------------
 
-Link a target to given libraries.
+.. only:: html
+
+   .. contents::
+
+Specify libraries or flags to use when linking a given target and/or
+its dependents.  :ref:`Usage requirements <Target Usage Requirements>`
+from linked library targets will be propagated.  Usage requirements
+of a target's dependencies affect compilation of its own sources.
+
+Overview
+^^^^^^^^
+
+This command has several signatures as detailed in subsections below.
+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`.
+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
+  full path to the linkable library file associated with the target.
+  The buildsystem will have a dependency to re-link ``<target>`` if
+  the library file changes.
+
+  The named target must be created by :command:`add_library` within
+  the project or as an :ref:`IMPORTED library <Imported Targets>`.
+  If it is created within the project an ordering dependency will
+  automatically be added in the build system to make sure the named
+  library target is up-to-date before the ``<target>`` links.
+
+* **A full path to a library file**: The generated link line will
+  normally preserve the full path to the file.  However, there are
+  some cases where CMake must ask the linker to search for the library
+  (e.g. ``/usr/lib/libfoo.so`` becomes ``-lfoo``), such as when it
+  appears in a system library directory that the compiler front-end
+  may replace with an alternative.  Either way, the buildsystem will
+  have a dependency to re-link ``<target>`` if the library file changes.
+
+  If the library file is in a Mac OSX framework, the ``Headers`` directory
+  of the framework will also be processed as a
+  :ref:`usage requirement <Target Usage Requirements>`.  This has the same
+  effect as passing the framework directory as an include directory.
+
+* **A plain library name**: The generated link line will ask the linker
+  to search for the library (e.g. ``foo`` becomes ``-lfoo`` or ``foo.lib``).
+
+* **A link flag**: Item names starting with ``-``, but not ``-l`` or
+  ``-framework``, are treated as linker flags.  Note that such flags will
+  be treated like any other library link item for purposes of transitive
+  dependencies, so they are generally safe to specify only as private link
+  items that will not propagate to dependents.
+
+* A ``debug``, ``optimized``, or ``general`` keyword immediately followed
+  by another ``<item>``.  The item following such a keyword will be used
+  only for the corresponding build configuration.  The ``debug`` keyword
+  corresponds to the ``Debug`` configuration (or to configurations named
+  in the :prop_gbl:`DEBUG_CONFIGURATIONS` global property if it is set).
+  The ``optimized`` keyword corresponds to all other configurations.  The
+  ``general`` keyword corresponds to all configurations, and is purely
+  optional.  Higher granularity may be achieved for per-configuration
+  rules by creating and linking to
+  :ref:`IMPORTED library targets <Imported Targets>`.
+
+Items containing ``::``, such as ``Foo::Bar``, are assumed to be
+:ref:`IMPORTED <Imported Targets>` or :ref:`ALIAS <Alias Targets>` library
+target names and will cause an error if no such target exists.
+See policy :policy:`CMP0028`.
+
+Arguments to ``target_link_libraries`` may use "generator expressions"
+with the syntax ``$<...>``.  Note however, that generator expressions
+will not be used in OLD handling of :policy:`CMP0003` or :policy:`CMP0004`.
+See the :manual:`cmake-generator-expressions(7)` manual for available
+expressions.  See the :manual:`cmake-buildsystem(7)` manual for more on
+defining buildsystem properties.
+
+Libraries for a Target and/or its Dependents
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+::
+
+  target_link_libraries(<target>
+                        <PRIVATE|PUBLIC|INTERFACE> <item>...
+                       [<PRIVATE|PUBLIC|INTERFACE> <item>...]...)
+
+The ``PUBLIC``, ``PRIVATE`` and ``INTERFACE`` keywords can be used to
+specify both the link dependencies and the link interface in one command.
+Libraries and targets following ``PUBLIC`` are linked to, and are made
+part of the link interface.  Libraries and targets following ``PRIVATE``
+are linked to, but are not made part of the link interface.  Libraries
+following ``INTERFACE`` are appended to the link interface and are not
+used for linking ``<target>``.
+
+Libraries for both a Target and its Dependents
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 ::
 
-  target_link_libraries(<target> [item1 [item2 [...]]]
-                        [[debug|optimized|general] <item>] ...)
-
-Specify libraries or flags to use when linking a given target.  The
-named ``<target>`` must have been created in the current directory by a
-command such as :command:`add_executable` or :command:`add_library`.  The
-remaining arguments specify library names or flags.  Repeated calls for
-the same ``<target>`` append items in the order called.
-
-If a library name matches that of another target in the project a
-dependency will automatically be added in the build system to make sure
-the library being linked is up-to-date before the target links. Item names
-starting with ``-``, but not ``-l`` or ``-framework``, are treated as
-linker flags.  Note that such flags will be treated like any other library
-link item for purposes of transitive dependencies, so they are generally
-safe to specify only as private link items that will not propagate to
-dependents of ``<target>``.
-
-A ``debug``, ``optimized``, or ``general`` keyword indicates that the
-library immediately following it is to be used only for the
-corresponding build configuration.  The ``debug`` keyword corresponds to
-the Debug configuration (or to configurations named in the
-:prop_gbl:`DEBUG_CONFIGURATIONS` global property if it is set).  The
-``optimized`` keyword corresponds to all other configurations.  The
-``general`` keyword corresponds to all configurations, and is purely
-optional (assumed if omitted).  Higher granularity may be achieved for
-per-configuration rules by creating and linking to
-:ref:`IMPORTED library targets <Imported Targets>`.
+  target_link_libraries(<target> <item>...)
 
 Library dependencies are transitive by default with this signature.
 When this target is linked into another target then the libraries
@@ -45,37 +114,34 @@ by setting the property directly.  When :policy:`CMP0022` is not set to
 of this command may set the property making any libraries linked
 exclusively by this signature private.
 
-CMake will also propagate :ref:`usage requirements <Target Usage Requirements>`
-from linked library targets.  Usage requirements of dependencies affect
-compilation of sources in the ``<target>``.
-
-If an ``<item>`` is a library in a Mac OX framework, the ``Headers``
-directory of the framework will also be processed as a
-:ref:`usage requirement <Target Usage Requirements>`.  This has the same
-effect as passing the framework directory as an include directory.
-
---------------------------------------------------------------------------
+Libraries for a Target and/or its Dependents (Legacy)
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 ::
 
   target_link_libraries(<target>
-                      <PRIVATE|PUBLIC|INTERFACE> <lib> ...
-                      [<PRIVATE|PUBLIC|INTERFACE> <lib> ... ] ...])
+                        <LINK_PRIVATE|LINK_PUBLIC> <lib>...
+                       [<LINK_PRIVATE|LINK_PUBLIC> <lib>...]...)
 
-The ``PUBLIC``, ``PRIVATE`` and ``INTERFACE`` keywords can be used to
-specify both the link dependencies and the link interface in one command.
-Libraries and targets following ``PUBLIC`` are linked to, and are made
-part of the link interface.  Libraries and targets following ``PRIVATE``
-are linked to, but are not made part of the link interface.  Libraries
-following ``INTERFACE`` are appended to the link interface and are not
-used for linking ``<target>``.
+The ``LINK_PUBLIC`` and ``LINK_PRIVATE`` modes can be used to specify both
+the link dependencies and the link interface in one command.
 
---------------------------------------------------------------------------
+This signature is for compatibility only.  Prefer the ``PUBLIC`` or
+``PRIVATE`` keywords instead.
+
+Libraries and targets following ``LINK_PUBLIC`` are linked to, and are
+made part of the :prop_tgt:`INTERFACE_LINK_LIBRARIES`.  If policy
+:policy:`CMP0022` is not ``NEW``, they are also made part of the
+:prop_tgt:`LINK_INTERFACE_LIBRARIES`.  Libraries and targets following
+``LINK_PRIVATE`` are linked to, but are not made part of the
+:prop_tgt:`INTERFACE_LINK_LIBRARIES` (or :prop_tgt:`LINK_INTERFACE_LIBRARIES`).
+
+Libraries for Dependents Only (Legacy)
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 ::
 
-  target_link_libraries(<target> LINK_INTERFACE_LIBRARIES
-                        [[debug|optimized|general] <lib>] ...)
+  target_link_libraries(<target> LINK_INTERFACE_LIBRARIES <item>...)
 
 The ``LINK_INTERFACE_LIBRARIES`` mode appends the libraries to the
 :prop_tgt:`INTERFACE_LINK_LIBRARIES` target property instead of using them
@@ -99,28 +165,8 @@ is not ``NEW``, they are also appended to the
 ``general`` (or without any keyword) are treated as if specified for both
 ``debug`` and ``optimized``.
 
---------------------------------------------------------------------------
-
-::
-
-  target_link_libraries(<target>
-                        <LINK_PRIVATE|LINK_PUBLIC>
-                          [[debug|optimized|general] <lib>] ...
-                        [<LINK_PRIVATE|LINK_PUBLIC>
-                          [[debug|optimized|general] <lib>] ...])
-
-The ``LINK_PUBLIC`` and ``LINK_PRIVATE`` modes can be used to specify both
-the link dependencies and the link interface in one command.
-
-This signature is for compatibility only.  Prefer the ``PUBLIC`` or
-``PRIVATE`` keywords instead.
-
-Libraries and targets following ``LINK_PUBLIC`` are linked to, and are
-made part of the :prop_tgt:`INTERFACE_LINK_LIBRARIES`.  If policy
-:policy:`CMP0022` is not ``NEW``, they are also made part of the
-:prop_tgt:`LINK_INTERFACE_LIBRARIES`.  Libraries and targets following
-``LINK_PRIVATE`` are linked to, but are not made part of the
-:prop_tgt:`INTERFACE_LINK_LIBRARIES` (or :prop_tgt:`LINK_INTERFACE_LIBRARIES`).
+Cyclic Dependencies of Static Libraries
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 The library dependency graph is normally acyclic (a DAG), but in the case
 of mutually-dependent ``STATIC`` libraries CMake allows the graph to
@@ -139,17 +185,11 @@ For example, the code
 
 links ``main`` to ``A B A B``.  While one repetition is usually
 sufficient, pathological object file and symbol arrangements can require
-more.  One may handle such cases by manually repeating the component in
-the last ``target_link_libraries`` call.  However, if two archives are
-really so interdependent they should probably be combined into a single
-archive.
-
-Arguments to target_link_libraries may use "generator expressions"
-with the syntax ``$<...>``.  Note however, that generator expressions
-will not be used in OLD handling of :policy:`CMP0003` or :policy:`CMP0004`.
-See the :manual:`cmake-generator-expressions(7)` manual for available
-expressions.  See the :manual:`cmake-buildsystem(7)` manual for more on
-defining buildsystem properties.
+more.  One may handle such cases by using the
+:prop_tgt:`LINK_INTERFACE_MULTIPLICITY` target property or by manually
+repeating the component in the last ``target_link_libraries`` call.
+However, if two archives are really so interdependent they should probably
+be combined into a single archive, perhaps by using :ref:`Object Libraries`.
 
 Creating Relocatable Packages
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^