Merge topic 'link-strategy' into release-3.31

39fd396421 LINK_LIBRARIES_STRATEGY: Rename strategies to clarify expectations

Acked-by: Kitware Robot <kwrobot@kitware.com>
Tested-by: buildbot <buildbot@kitware.com>
Acked-by: Craig Scott <craig.scott@crascit.com>
Merge-request: !9949

27 files changed, 32 insertions, 29 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,
diff --git a/Source/cmComputeLinkDepends.cxx b/Source/cmComputeLinkDepends.cxx
index ab2557b..551a45b 100644
--- a/Source/cmComputeLinkDepends.cxx
+++ b/Source/cmComputeLinkDepends.cxx
@@ -1521,14 +1521,14 @@ void cmComputeLinkDepends::OrderLinkEntries()
 
   // Start with the original link line.
   switch (this->Strategy) {
-    case LinkLibrariesStrategy::PRESERVE_ORDER: {
+    case LinkLibrariesStrategy::REORDER_MINIMALLY: {
       // Emit the direct dependencies in their original order.
       // This gives projects control over ordering.
       for (size_t originalEntry : this->OriginalEntries) {
         this->VisitEntry(originalEntry);
       }
     } break;
-    case LinkLibrariesStrategy::REORDER: {
+    case LinkLibrariesStrategy::REORDER_FREELY: {
       // Schedule the direct dependencies for emission in topo order.
       // This may produce more efficient link lines.
       for (size_t originalEntry : this->OriginalEntries) {
diff --git a/Source/cmComputeLinkDepends.h b/Source/cmComputeLinkDepends.h
index 8b8aba4..dc2fa45 100644
--- a/Source/cmComputeLinkDepends.h
+++ b/Source/cmComputeLinkDepends.h
@@ -29,8 +29,8 @@ class cmake;
 
 enum class LinkLibrariesStrategy
 {
-  PRESERVE_ORDER,
-  REORDER,
+  REORDER_MINIMALLY,
+  REORDER_FREELY,
 };
 
 /** \class cmComputeLinkDepends
diff --git a/Source/cmComputeLinkInformation.cxx b/Source/cmComputeLinkInformation.cxx
index 26ff326..c2c210b 100644
--- a/Source/cmComputeLinkInformation.cxx
+++ b/Source/cmComputeLinkInformation.cxx
@@ -568,12 +568,12 @@ bool cmComputeLinkInformation::Compute()
     return false;
   }
 
-  LinkLibrariesStrategy strategy = LinkLibrariesStrategy::PRESERVE_ORDER;
+  LinkLibrariesStrategy strategy = LinkLibrariesStrategy::REORDER_MINIMALLY;
   if (cmValue s = this->Target->GetProperty("LINK_LIBRARIES_STRATEGY")) {
-    if (*s == "PRESERVE_ORDER"_s) {
-      strategy = LinkLibrariesStrategy::PRESERVE_ORDER;
-    } else if (*s == "REORDER"_s) {
-      strategy = LinkLibrariesStrategy::REORDER;
+    if (*s == "REORDER_MINIMALLY"_s) {
+      strategy = LinkLibrariesStrategy::REORDER_MINIMALLY;
+    } else if (*s == "REORDER_FREELY"_s) {
+      strategy = LinkLibrariesStrategy::REORDER_FREELY;
     } else {
       this->CMakeInstance->IssueMessage(
         MessageType::FATAL_ERROR,
diff --git a/Tests/RunCMake/LinkLibrariesStrategy/Basic-PRESERVE_ORDER.cmake b/Tests/RunCMake/LinkLibrariesStrategy/Basic-PRESERVE_ORDER.cmake
deleted file mode 100644
index f3dc096..0000000
--- a/Tests/RunCMake/LinkLibrariesStrategy/Basic-PRESERVE_ORDER.cmake
+++ /dev/null
@@ -1,2 +0,0 @@
-set(CMAKE_LINK_LIBRARIES_STRATEGY PRESERVE_ORDER)
-include(Basic-common.cmake)
diff --git a/Tests/RunCMake/LinkLibrariesStrategy/Basic-REORDER.cmake b/Tests/RunCMake/LinkLibrariesStrategy/Basic-REORDER.cmake
deleted file mode 100644
index 8e62377..0000000
--- a/Tests/RunCMake/LinkLibrariesStrategy/Basic-REORDER.cmake
+++ /dev/null
@@ -1,2 +0,0 @@
-set(CMAKE_LINK_LIBRARIES_STRATEGY REORDER)
-include(Basic-common.cmake)
diff --git a/Tests/RunCMake/LinkLibrariesStrategy/Basic-REORDER-run-stdout.txt b/Tests/RunCMake/LinkLibrariesStrategy/Basic-REORDER_FREELY-run-stdout-dedup-reverse.txt
index 7e46d1ba..7e46d1ba 100644
--- a/Tests/RunCMake/LinkLibrariesStrategy/Basic-REORDER-run-stdout.txt
+++ b/Tests/RunCMake/LinkLibrariesStrategy/Basic-REORDER_FREELY-run-stdout-dedup-reverse.txt
diff --git a/Tests/RunCMake/LinkLibrariesStrategy/Basic-REORDER-run-stdout-dedup.txt b/Tests/RunCMake/LinkLibrariesStrategy/Basic-REORDER_FREELY-run-stdout-dedup.txt
index 7e46d1ba..7e46d1ba 100644
--- a/Tests/RunCMake/LinkLibrariesStrategy/Basic-REORDER-run-stdout-dedup.txt
+++ b/Tests/RunCMake/LinkLibrariesStrategy/Basic-REORDER_FREELY-run-stdout-dedup.txt
diff --git a/Tests/RunCMake/LinkLibrariesStrategy/Basic-REORDER-run-stdout-dedup-reverse.txt b/Tests/RunCMake/LinkLibrariesStrategy/Basic-REORDER_FREELY-run-stdout.txt
index 7e46d1ba..7e46d1ba 100644
--- a/Tests/RunCMake/LinkLibrariesStrategy/Basic-REORDER-run-stdout-dedup-reverse.txt
+++ b/Tests/RunCMake/LinkLibrariesStrategy/Basic-REORDER_FREELY-run-stdout.txt
diff --git a/Tests/RunCMake/LinkLibrariesStrategy/Basic-REORDER-stderr.txt b/Tests/RunCMake/LinkLibrariesStrategy/Basic-REORDER_FREELY-stderr-dedup-reverse.txt
index b908fbc..b908fbc 100644
--- a/Tests/RunCMake/LinkLibrariesStrategy/Basic-REORDER-stderr.txt
+++ b/Tests/RunCMake/LinkLibrariesStrategy/Basic-REORDER_FREELY-stderr-dedup-reverse.txt
diff --git a/Tests/RunCMake/LinkLibrariesStrategy/Basic-REORDER-stderr-dedup.txt b/Tests/RunCMake/LinkLibrariesStrategy/Basic-REORDER_FREELY-stderr-dedup.txt
index b908fbc..b908fbc 100644
--- a/Tests/RunCMake/LinkLibrariesStrategy/Basic-REORDER-stderr-dedup.txt
+++ b/Tests/RunCMake/LinkLibrariesStrategy/Basic-REORDER_FREELY-stderr-dedup.txt
diff --git a/Tests/RunCMake/LinkLibrariesStrategy/Basic-REORDER-stderr-dedup-reverse.txt b/Tests/RunCMake/LinkLibrariesStrategy/Basic-REORDER_FREELY-stderr.txt
index b908fbc..b908fbc 100644
--- a/Tests/RunCMake/LinkLibrariesStrategy/Basic-REORDER-stderr-dedup-reverse.txt
+++ b/Tests/RunCMake/LinkLibrariesStrategy/Basic-REORDER_FREELY-stderr.txt
diff --git a/Tests/RunCMake/LinkLibrariesStrategy/Basic-REORDER_FREELY.cmake b/Tests/RunCMake/LinkLibrariesStrategy/Basic-REORDER_FREELY.cmake
new file mode 100644
index 0000000..ea38b5b
--- /dev/null
+++ b/Tests/RunCMake/LinkLibrariesStrategy/Basic-REORDER_FREELY.cmake
@@ -0,0 +1,2 @@
+set(CMAKE_LINK_LIBRARIES_STRATEGY REORDER_FREELY)
+include(Basic-common.cmake)
diff --git a/Tests/RunCMake/LinkLibrariesStrategy/Basic-PRESERVE_ORDER-run-stdout-dedup-reverse.txt b/Tests/RunCMake/LinkLibrariesStrategy/Basic-REORDER_MINIMALLY-run-stdout-dedup-reverse.txt
index 7e46d1ba..7e46d1ba 100644
--- a/Tests/RunCMake/LinkLibrariesStrategy/Basic-PRESERVE_ORDER-run-stdout-dedup-reverse.txt
+++ b/Tests/RunCMake/LinkLibrariesStrategy/Basic-REORDER_MINIMALLY-run-stdout-dedup-reverse.txt
diff --git a/Tests/RunCMake/LinkLibrariesStrategy/Basic-PRESERVE_ORDER-run-stdout.txt b/Tests/RunCMake/LinkLibrariesStrategy/Basic-REORDER_MINIMALLY-run-stdout-dedup.txt
index 6ef12eb..6ef12eb 100644
--- a/Tests/RunCMake/LinkLibrariesStrategy/Basic-PRESERVE_ORDER-run-stdout.txt
+++ b/Tests/RunCMake/LinkLibrariesStrategy/Basic-REORDER_MINIMALLY-run-stdout-dedup.txt
diff --git a/Tests/RunCMake/LinkLibrariesStrategy/Basic-PRESERVE_ORDER-run-stdout-dedup.txt b/Tests/RunCMake/LinkLibrariesStrategy/Basic-REORDER_MINIMALLY-run-stdout.txt
index 6ef12eb..6ef12eb 100644
--- a/Tests/RunCMake/LinkLibrariesStrategy/Basic-PRESERVE_ORDER-run-stdout-dedup.txt
+++ b/Tests/RunCMake/LinkLibrariesStrategy/Basic-REORDER_MINIMALLY-run-stdout.txt
diff --git a/Tests/RunCMake/LinkLibrariesStrategy/Basic-PRESERVE_ORDER-stderr-dedup-reverse.txt b/Tests/RunCMake/LinkLibrariesStrategy/Basic-REORDER_MINIMALLY-stderr-dedup-reverse.txt
index 7d91bee..7d91bee 100644
--- a/Tests/RunCMake/LinkLibrariesStrategy/Basic-PRESERVE_ORDER-stderr-dedup-reverse.txt
+++ b/Tests/RunCMake/LinkLibrariesStrategy/Basic-REORDER_MINIMALLY-stderr-dedup-reverse.txt
diff --git a/Tests/RunCMake/LinkLibrariesStrategy/Basic-PRESERVE_ORDER-stderr-dedup.txt b/Tests/RunCMake/LinkLibrariesStrategy/Basic-REORDER_MINIMALLY-stderr-dedup.txt
index d4bccc4..d4bccc4 100644
--- a/Tests/RunCMake/LinkLibrariesStrategy/Basic-PRESERVE_ORDER-stderr-dedup.txt
+++ b/Tests/RunCMake/LinkLibrariesStrategy/Basic-REORDER_MINIMALLY-stderr-dedup.txt
diff --git a/Tests/RunCMake/LinkLibrariesStrategy/Basic-PRESERVE_ORDER-stderr.txt b/Tests/RunCMake/LinkLibrariesStrategy/Basic-REORDER_MINIMALLY-stderr.txt
index 7e9a1cd..7e9a1cd 100644
--- a/Tests/RunCMake/LinkLibrariesStrategy/Basic-PRESERVE_ORDER-stderr.txt
+++ b/Tests/RunCMake/LinkLibrariesStrategy/Basic-REORDER_MINIMALLY-stderr.txt
diff --git a/Tests/RunCMake/LinkLibrariesStrategy/Basic-REORDER_MINIMALLY.cmake b/Tests/RunCMake/LinkLibrariesStrategy/Basic-REORDER_MINIMALLY.cmake
new file mode 100644
index 0000000..12876b1
--- /dev/null
+++ b/Tests/RunCMake/LinkLibrariesStrategy/Basic-REORDER_MINIMALLY.cmake
@@ -0,0 +1,2 @@
+set(CMAKE_LINK_LIBRARIES_STRATEGY REORDER_MINIMALLY)
+include(Basic-common.cmake)
diff --git a/Tests/RunCMake/LinkLibrariesStrategy/Duplicate-PRESERVE_ORDER.cmake b/Tests/RunCMake/LinkLibrariesStrategy/Duplicate-PRESERVE_ORDER.cmake
deleted file mode 100644
index 9f694db..0000000
--- a/Tests/RunCMake/LinkLibrariesStrategy/Duplicate-PRESERVE_ORDER.cmake
+++ /dev/null
@@ -1,2 +0,0 @@
-set(CMAKE_LINK_LIBRARIES_STRATEGY PRESERVE_ORDER)
-include(Duplicate-common.cmake)
diff --git a/Tests/RunCMake/LinkLibrariesStrategy/Duplicate-REORDER.cmake b/Tests/RunCMake/LinkLibrariesStrategy/Duplicate-REORDER.cmake
deleted file mode 100644
index cc51e0a..0000000
--- a/Tests/RunCMake/LinkLibrariesStrategy/Duplicate-REORDER.cmake
+++ /dev/null
@@ -1,2 +0,0 @@
-set(CMAKE_LINK_LIBRARIES_STRATEGY REORDER)
-include(Duplicate-common.cmake)
diff --git a/Tests/RunCMake/LinkLibrariesStrategy/Duplicate-REORDER-stderr.txt b/Tests/RunCMake/LinkLibrariesStrategy/Duplicate-REORDER_FREELY-stderr.txt
index 2353288..2353288 100644
--- a/Tests/RunCMake/LinkLibrariesStrategy/Duplicate-REORDER-stderr.txt
+++ b/Tests/RunCMake/LinkLibrariesStrategy/Duplicate-REORDER_FREELY-stderr.txt
diff --git a/Tests/RunCMake/LinkLibrariesStrategy/Duplicate-REORDER_FREELY.cmake b/Tests/RunCMake/LinkLibrariesStrategy/Duplicate-REORDER_FREELY.cmake
new file mode 100644
index 0000000..c205fad
--- /dev/null
+++ b/Tests/RunCMake/LinkLibrariesStrategy/Duplicate-REORDER_FREELY.cmake
@@ -0,0 +1,2 @@
+set(CMAKE_LINK_LIBRARIES_STRATEGY REORDER_FREELY)
+include(Duplicate-common.cmake)
diff --git a/Tests/RunCMake/LinkLibrariesStrategy/Duplicate-PRESERVE_ORDER-stderr.txt b/Tests/RunCMake/LinkLibrariesStrategy/Duplicate-REORDER_MINIMALLY-stderr.txt
index 2637f93..2637f93 100644
--- a/Tests/RunCMake/LinkLibrariesStrategy/Duplicate-PRESERVE_ORDER-stderr.txt
+++ b/Tests/RunCMake/LinkLibrariesStrategy/Duplicate-REORDER_MINIMALLY-stderr.txt
diff --git a/Tests/RunCMake/LinkLibrariesStrategy/Duplicate-REORDER_MINIMALLY.cmake b/Tests/RunCMake/LinkLibrariesStrategy/Duplicate-REORDER_MINIMALLY.cmake
new file mode 100644
index 0000000..6d4545b
--- /dev/null
+++ b/Tests/RunCMake/LinkLibrariesStrategy/Duplicate-REORDER_MINIMALLY.cmake
@@ -0,0 +1,2 @@
+set(CMAKE_LINK_LIBRARIES_STRATEGY REORDER_MINIMALLY)
+include(Duplicate-common.cmake)
diff --git a/Tests/RunCMake/LinkLibrariesStrategy/RunCMakeTest.cmake b/Tests/RunCMake/LinkLibrariesStrategy/RunCMakeTest.cmake
index eb107ed..787b636 100644
--- a/Tests/RunCMake/LinkLibrariesStrategy/RunCMakeTest.cmake
+++ b/Tests/RunCMake/LinkLibrariesStrategy/RunCMakeTest.cmake
@@ -44,8 +44,8 @@ function(run_strategy case exe)
   endforeach()
 endfunction()
 
-run_strategy(Basic-PRESERVE_ORDER "main")
-run_strategy(Basic-REORDER "main")
+run_strategy(Basic-REORDER_MINIMALLY "main")
+run_strategy(Basic-REORDER_FREELY "main")
 
-run_cmake(Duplicate-PRESERVE_ORDER)
-run_cmake(Duplicate-REORDER)
+run_cmake(Duplicate-REORDER_MINIMALLY)
+run_cmake(Duplicate-REORDER_FREELY)