Link step: Enable to configure deduplication of libraries

Some platforms, Apple or Windows for instance, do not require to duplicate
static libraries to resolve mutual dependencies. Moreover, Xcode version 15
emits a warning if a library is duplicated.
On Windows, enable a better control of libraries order.

Fixes: #20722, #25297

1 files changed, 47 insertions, 0 deletions

diff --git a/Help/policy/CMP0156.rst b/Help/policy/CMP0156.rst
new file mode 100644
index 0000000..fa97519
--- /dev/null
+++ b/Help/policy/CMP0156.rst
@@ -0,0 +1,47 @@
+CMP0156
+-------
+
+.. versionadded:: 3.29
+
+De-duplicate libraries on link lines based on linker capabilities.
+
+Traditional linkers maintain a set of undefined symbols during linking. The
+linker processes each file in the order in which it appears on the command
+line, until the set of undefined symbols becomes empty. An object file is
+linked into the output object when it is encountered, with its undefined
+symbols added to the set. Upon encountering an archive file a traditional
+linker searches the objects contained therein, and processes those that satisfy
+symbols in the unresolved set.
+
+Handling mutually dependent archives may be awkward when using a traditional
+linker. Archive files may have to be specified multiple times.
+
+Some linkers (for instance Apple or Windows linkers, as well as``LLVM LLD``)
+records all symbols found in objects and archives as it iterates over command
+line arguments. When one of these linkers encounters an undefined symbol that
+can be resolved by an object file contained in a previously processed archive
+file, it immediately extracts and links it into the output object.
+
+CMake 3.28 and below may generate link lines that repeat static libraries as
+a traditional linker would need, even when using a linker does not need it.
+They may also de-duplicate shared libraries by keeping their last occurrence,
+which on Windows platforms can change DLL load order.
+
+CMake 3.29 and above prefer to apply different strategies based on linker
+capabilities.  So, when targeting Apple and Windows platforms, all
+libraries are de-duplicated.  Moreover, on Windows platforms, libraries
+are de-duplicated by keeping their fist occurrence, thus respecting the
+project-specified order.  This policy provides compatibility with projects
+that have not been updated to expect the latter behavior.
+
+The ``OLD`` behavior for this policy is to always repeat static libraries
+as if using a traditional linker, and always de-duplicate shared libraries
+by keeping the last occurrence of each.  The ``NEW`` behavior for this policy
+is to apply different strategies based on linker capabilities.
+
+This policy was introduced in CMake version 3.29.  Use the
+:command:`cmake_policy` command to set it to ``OLD`` or ``NEW`` explicitly.
+Unlike many policies, CMake version |release| does *not* warn
+when this policy is not set and simply uses ``OLD`` behavior.
+
+.. include:: DEPRECATED.txt