Link Step: compute effective linker used by the compiler

Extract the effective linker during the computation of implicit artifacts
delivered by the compiler to the linker.
Define various variables describing the linker:
* CMAKE_<LANG>_COMPILER_LINKER
* CMAKE_<LANG>_COMPILER_LINKER_VERSION
* CMAKE_<LANG>_COMPILER_LINKER_ID
* CMAKE_<LANG>_COMPILER_LINKER_FRONTEND_VARIANT

This is complementary to feature introduced by commit 96a953b1ed
(Add options to specify linker tool, 2023-09-27).

Fixes: #17596, #18209, #25344

6 files changed, 89 insertions, 0 deletions

diff --git a/Help/manual/cmake-variables.7.rst b/Help/manual/cmake-variables.7.rst
index 9320ffa..bf6fc0a 100644
--- a/Help/manual/cmake-variables.7.rst
+++ b/Help/manual/cmake-variables.7.rst
@@ -74,6 +74,10 @@ Variables that Provide Information
    /variable/CMAKE_JOB_POOLS
    /variable/CMAKE_LANG_COMPILER_AR
    /variable/CMAKE_LANG_COMPILER_FRONTEND_VARIANT
+   /variable/CMAKE_LANG_COMPILER_LINKER
+   /variable/CMAKE_LANG_COMPILER_LINKER_FRONTEND_VARIANT
+   /variable/CMAKE_LANG_COMPILER_LINKER_ID
+   /variable/CMAKE_LANG_COMPILER_LINKER_VERSION
    /variable/CMAKE_LANG_COMPILER_RANLIB
    /variable/CMAKE_LANG_LINK_LIBRARY_SUFFIX
    /variable/CMAKE_LINK_LIBRARY_SUFFIX
diff --git a/Help/release/dev/compiler-linker.rst b/Help/release/dev/compiler-linker.rst
new file mode 100644
index 0000000..4783656
--- /dev/null
+++ b/Help/release/dev/compiler-linker.rst
@@ -0,0 +1,8 @@
+compiler-linker
+---------------
+
+* The linker effectively used for the link step is now documented with the
+  :variable:`CMAKE_<LANG>_COMPILER_LINKER`,
+  :variable:`CMAKE_<LANG>_COMPILER_LINKER_ID`,
+  :variable:`CMAKE_<LANG>_COMPILER_LINKER_VERSION` and
+  :variable:`CMAKE_<LANG>_COMPILER_LINKER_FRONTEND_VARIANT` variables.
diff --git a/Help/variable/CMAKE_LANG_COMPILER_LINKER.rst b/Help/variable/CMAKE_LANG_COMPILER_LINKER.rst
new file mode 100644
index 0000000..c0ae1cd
--- /dev/null
+++ b/Help/variable/CMAKE_LANG_COMPILER_LINKER.rst
@@ -0,0 +1,15 @@
+CMAKE_<LANG>_COMPILER_LINKER
+----------------------------
+
+.. versionadded:: 3.29
+
+The full path to the linker for ``LANG``.
+
+This is the command that will be used as the ``<LANG>`` linker.
+
+This variable is not guaranteed to be defined for all linkers or languages.
+
+.. note::
+  This variable is read-only. It must not be set by the user. To select a
+  specific linker, use the :variable:`CMAKE_LINKER_TYPE` variable or the
+  :prop_tgt:`LINKER_TYPE` target property.
diff --git a/Help/variable/CMAKE_LANG_COMPILER_LINKER_FRONTEND_VARIANT.rst b/Help/variable/CMAKE_LANG_COMPILER_LINKER_FRONTEND_VARIANT.rst
new file mode 100644
index 0000000..d7d028a
--- /dev/null
+++ b/Help/variable/CMAKE_LANG_COMPILER_LINKER_FRONTEND_VARIANT.rst
@@ -0,0 +1,21 @@
+CMAKE_<LANG>_COMPILER_LINKER_FRONTEND_VARIANT
+---------------------------------------------
+
+.. versionadded:: 3.29
+
+Identification string of the linker frontend variant.
+
+Some linkers have multiple, different frontends for accepting command
+line options.  (For example ``LLCM LLD`` originally only had a frontend
+compatible with the ``GNU`` compiler but since its port to Windows
+(``lld-link``) it now also supports a frontend compatible with ``MSVC``.)
+When CMake detects such a linker it sets this variable to what would have been
+the :variable:`CMAKE_<LANG>_COMPILER_LINKER_ID` for the linker whose frontend
+it resembles.
+
+.. note::
+  In other words, this variable describes what command line options
+  and language extensions the linker frontend expects.
+
+  This variable is set for ``GNU``, ``MSVC``, ``MOLD`` and ``AppleClang``
+  linkers that have only one frontend variant.
diff --git a/Help/variable/CMAKE_LANG_COMPILER_LINKER_ID.rst b/Help/variable/CMAKE_LANG_COMPILER_LINKER_ID.rst
new file mode 100644
index 0000000..560f522
--- /dev/null
+++ b/Help/variable/CMAKE_LANG_COMPILER_LINKER_ID.rst
@@ -0,0 +1,31 @@
+CMAKE_<LANG>_COMPILER_LINKER_ID
+-------------------------------
+
+.. versionadded:: 3.29
+
+Linker identification string.
+
+A short string unique to the linker vendor.  Possible values
+include:
+
+=============================== ===============================================
+Value                           Name
+=============================== ===============================================
+``AppleClang``                  Apple Clang
+``LLD``                         `LLVM LLD`_
+``GNU``                         `GNU Binutils - ld linker`_ (also known as
+                                ``bfd``)
+``GNUgold``                     `GNU Binutils - gold linker`_
+``MSVC``                        `Microsoft Visual Studio`_
+``MOLD``                        `mold: A Modern Linker`_ or, on Apple, `sold`_
+                                linker
+=============================== ===============================================
+
+This variable is not guaranteed to be defined for all linkers or languages.
+
+.. _LLVM LLD: https://lld.llvm.org
+.. _GNU Binutils - ld linker: https://sourceware.org/binutils
+.. _GNU Binutils - gold linker: https://sourceware.org/binutils
+.. _Microsoft Visual Studio: https://visualstudio.microsoft.com
+.. _mold\: A Modern Linker: https://github.com/rui314/mold
+.. _sold: https://github.com/bluewhalesystems/sold
diff --git a/Help/variable/CMAKE_LANG_COMPILER_LINKER_VERSION.rst b/Help/variable/CMAKE_LANG_COMPILER_LINKER_VERSION.rst
new file mode 100644
index 0000000..72b0551
--- /dev/null
+++ b/Help/variable/CMAKE_LANG_COMPILER_LINKER_VERSION.rst
@@ -0,0 +1,10 @@
+CMAKE_<LANG>_COMPILER_LINKER_VERSION
+------------------------------------
+
+.. versionadded:: 3.29
+
+Linker version string.
+
+Linker version in major[.minor[.patch[.tweak]]] format.  This
+variable is not guaranteed to be defined for all linkers or
+languages.