LINK_LIBRARIES_STRATEGY: Rename strategies to clarify expectations

Since commit 7abd3137b7 (Linking: Optionally reorder direct dependencies
from LINK_LIBRARIES, 2024-09-19, v3.31.0-rc1~53^2) the strategy name
`PRESERVE_ORDER` has led users to expect that it strictly preserves
order.  While the part of the link line generation logic controlled by
`LINK_LIBRARIES_STRATEGY` does preserve order, it is not the last step.
Toolchain-specific de-duplication can cause the order to change on the
actual link line generated in the build system.

Rename the strategies:

* `PRESERVE_ORDER` => `REORDER_MINIMALLY`
* `REORDER`        => `REORDER_FREELY`

The new names make it clear that reordering is always possible, just to
varying degrees.  Update the `LINK_LIBRARIES_STRATEGY` documentation to
clarify that the strategies do not directly control the final link line.

Fixes: #26400
Issue: #26271

1 files changed, 11 insertions, 8 deletions

diff --git a/Help/prop_tgt/LINK_LIBRARIES_STRATEGY.rst b/Help/prop_tgt/LINK_LIBRARIES_STRATEGY.rst
index 13a5d52..f8db750 100644
--- a/Help/prop_tgt/LINK_LIBRARIES_STRATEGY.rst
+++ b/Help/prop_tgt/LINK_LIBRARIES_STRATEGY.rst
@@ -15,7 +15,8 @@ target's direct link dependencies, typically populated by calls to
 propagated from those entries of :prop_tgt:`LINK_LIBRARIES` that name
 library targets by following the transitive closure of their
 :prop_tgt:`INTERFACE_LINK_LIBRARIES` properties.  CMake supports multiple
-strategies for passing direct and indirect link dependencies to the linker.
+strategies for nominally ordering direct and indirect link dependencies,
+which are then filtered for `Toolchain-Specific Behavior`_.
 
 Consider this example for the strategies below:
 
@@ -31,7 +32,7 @@ Consider this example for the strategies below:
 
 The supported strategies are:
 
-``PRESERVE_ORDER``
+``REORDER_MINIMALLY``
   Entries of :prop_tgt:`LINK_LIBRARIES` always appear first and in their
   original order.  Indirect link dependencies not satisfied by the
   original entries may be reordered and de-duplicated with respect to
@@ -46,13 +47,13 @@ The supported strategies are:
   In the above example, this strategy computes a link line for ``main``
   by starting with its original entries ``A B C``, and then appends
   another ``A`` to satisfy the dependencies of ``B`` and ``C`` on ``A``.
-  The final order produced by this strategy is ``A B C A``.
+  The nominal order produced by this strategy is ``A B C A``.
 
   Note that additional filtering for `Toolchain-Specific Behavior`_
   may de-duplicate ``A`` on the actual linker invocation in the
   generated build system, resulting in either ``A B C`` or ``B C A``.
 
-``REORDER``
+``REORDER_FREELY``
   Entries of :prop_tgt:`LINK_LIBRARIES` may be reordered, de-duplicated,
   and intermixed with indirect link dependencies.  This may result in
   more efficient link lines, but does not give projects any control of
@@ -61,16 +62,18 @@ The supported strategies are:
   In the above example, this strategy computes a link line for ``main``
   by re-ordering its original entries ``A B C`` to satisfy the
   dependencies of ``B`` and ``C`` on ``A``.
-  The final order produced by this strategy is ``B C A``.
+  The nominal order produced by this strategy is ``B C A``.
 
 Toolchain-Specific Behavior
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-Regardless of the strategy used, the actual linker invocation for
-some platforms may de-duplicate entries based on linker capabilities.
+After one of the above strategies produces a nominal order among
+direct and indirect link dependencies, the actual linker invocation
+in the generated build system may de-duplicate entries based on
+platform-specific requirements and linker capabilities.
 See policy :policy:`CMP0156`.
 
-For example, if the ``PRESERVE_ORDER`` strategy produces ``A B C A``,
+For example, if the ``REORDER_MINIMALLY`` strategy produces ``A B C A``,
 the actual link line may de-duplicate ``A`` as follows:
 
 * If ``A`` is a static library and the linker re-scans automatically,