Add options to specify linker tool

Offer the capability, through variable `CMAKE_LINKER_TYPE`, as well as
the target property `LINKER_TYPE` to specify which linker must be used.

The implementation of this capability is specified by variables specific
to the language and linker type: `CMAKE_<LANG>_USING_LINKER_<TYPE>`.
Some definitions are provided as part of `CMake`.

For example, to select the `LLVM` linker rather than the standard one,
the type `LLD` should be specified through the variable `CMAKE_LINKER_TYPE`.
And, on `Apple`, `Linux` and some environments on `Windows`, the variable
`CMAKE_<LANG>_USING_LINKER_LLD` has value `-fuse-ld=lld`. And for `Windows`
environments  based on `MSVC`, where the linker is used directly, the tool
`lld-link.exe` will be used rather than `link.exe`.

Fixes: #19174, #24254, #24990

4 files changed, 120 insertions, 0 deletions

diff --git a/Help/variable/CMAKE_LANG_USING_LINKER_MODE.rst b/Help/variable/CMAKE_LANG_USING_LINKER_MODE.rst
new file mode 100644
index 0000000..c9b6779
--- /dev/null
+++ b/Help/variable/CMAKE_LANG_USING_LINKER_MODE.rst
@@ -0,0 +1,15 @@
+CMAKE_<LANG>_USING_LINKER_MODE
+------------------------------
+
+.. versionadded:: 3.29
+
+This variable specify what is the type of data stored in variable
+ :variable:`CMAKE_<LANG>_USING_LINKER_<TYPE>`. There are two possible values:
+
+``FLAG``
+  :variable:`CMAKE_<LANG>_USING_LINKER_<TYPE>` holds compiler flags. This is
+  the default.
+
+``TOOL``
+  :variable:`CMAKE_<LANG>_USING_LINKER_<TYPE>` holds the path to the linker
+  tool.
diff --git a/Help/variable/CMAKE_LANG_USING_LINKER_TYPE.rst b/Help/variable/CMAKE_LANG_USING_LINKER_TYPE.rst
new file mode 100644
index 0000000..e4d9fa6
--- /dev/null
+++ b/Help/variable/CMAKE_LANG_USING_LINKER_TYPE.rst
@@ -0,0 +1,30 @@
+CMAKE_<LANG>_USING_LINKER_<TYPE>
+--------------------------------
+
+.. versionadded:: 3.29
+
+This variable defines how to specify the linker for the link step for the type
+as specified by the variable :variable:`CMAKE_LINKER_TYPE` or the target
+property :prop_tgt:`LINKER_TYPE`. It can hold compiler flags for the link step
+or directly the linker tool. The type of data is given by the variable
+:variable:`CMAKE_<LANG>_USING_LINKER_MODE`.
+
+For example, to specify the ``LLVM`` linker for ``GNU`` compilers, we have:
+
+.. code-block:: cmake
+
+  set(CMAKE_C_USING_LINKER_LLD "-fuse-ld=lld")
+
+Or on ``Windows`` platform, for ``Clang`` compilers simulating ``MSVC``, we
+have:
+
+.. code-block:: cmake
+
+  set(CMAKE_C_USING_LINKER_LLD "-fuse-ld=lld-link")
+
+And for the ``MSVC`` compiler, linker is directly used, so we have:
+
+.. code-block:: cmake
+
+  set(CMAKE_C_USING_LINKER_LLD "/path/to/lld-link.exe")
+  set(CMAKE_C_USING_LINKER_MODE TOOL)
diff --git a/Help/variable/CMAKE_LINKER_TYPE.rst b/Help/variable/CMAKE_LINKER_TYPE.rst
new file mode 100644
index 0000000..17ea947
--- /dev/null
+++ b/Help/variable/CMAKE_LINKER_TYPE.rst
@@ -0,0 +1,18 @@
+CMAKE_LINKER_TYPE
+-----------------
+
+.. versionadded:: 3.29
+
+Specify which linker will be used for the link step.
+
+.. note::
+  It is assumed that the linker specified is fully compatible with the standard
+  one. CMake will not do any options translation.
+
+This variable is used to initialize the :prop_tgt:`LINKER_TYPE` target
+property when they are created by calls to :command:`add_library` or
+:command:`add_executable` commands. It is meaningful only for targets having a
+link step. If set, its value is also used by the :command:`try_compile`
+command.
+
+.. include:: LINKER_PREDEFINED_TYPES.txt
diff --git a/Help/variable/LINKER_PREDEFINED_TYPES.txt b/Help/variable/LINKER_PREDEFINED_TYPES.txt
new file mode 100644
index 0000000..50dc3df
--- /dev/null
+++ b/Help/variable/LINKER_PREDEFINED_TYPES.txt
@@ -0,0 +1,57 @@
+Linker types are case-sensitive and may only contain letters, numbers and
+underscores. Linker types defined in all uppercase are reserved for CMake's own
+built-in types. The pre-defined linker types are:
+
+``DEFAULT``
+  This type corresponds to standard linking, essentially equivalent to
+  not specifying :prop_tgt:`LINKER_TYPE` target property.
+
+``SYSTEM``
+  Use the standard linker delivered by the platform or the standard toolkit
+  (for example, ``SYSTEM`` imply Microsoft linker for all ``MSVC`` compatible
+  compilers). This type is supported for the following platforms/compilers:
+
+  * Linux, for ``GNU``, ``Clang`` and ``NVIDIA`` compilers.
+  * All Apple variants for ``AppleClang``, ``Clang`` and ``GNU`` compilers.
+  * Windows, for ``MSVC``, ``GNU``, ``Clang`` and ``NVIDIA`` compilers.
+
+``LLD``
+  Use the ``LLVM`` linker. This type is supported for the following
+  platforms/compilers:
+
+  * Linux, for ``GNU``, ``Clang`` and ``NVIDIA`` compilers.
+  * All Apple variants for ``Clang`` and ``AppleClang`` compilers.
+  * Windows, for ``GNU``, ``Clang`` compilers with ``GNU`` front-end and
+    ``CLang``, ``MSVC`` and ``NVIDIA`` compilers with ``MSVC`` front-end.
+
+``BFD``
+  Use the ``GNU`` linker.  This type is supported for the following
+  platforms/compilers:
+
+  * Linux, for ``GNU``, ``Clang`` and ``NVIDIA`` compilers.
+  * Windows, for ``GNU``, ``Clang`` compilers with ``GNU`` front-end.
+
+``GOLD``
+  Supported on Linux platform for ``GNU``, ``Clang`` and ``NVIDIA`` compilers.
+
+``MOLD``
+  Use the `mold linker <https://github.com/rui314/mold>`_. This type is
+  supported on the following platforms:
+
+  * Linux platform for ``GNU``, ``Clang`` and ``NVIDIA`` compilers.
+  * All Apple variants for ``Clang`` and ``AppleClang`` compilers as an
+    alias to ``SOLD``.
+
+``SOLD``
+  Use the `sold linker <https://github.com/bluewhalesystems/sold>`_. This type
+  is only supported on Apple platforms for ``Clang`` and ``AppleClang``
+  compilers.
+
+``APPLE_CLASSIC``
+  Use the Apple linker in the classic behavior (i.e. before ``Xcode 15.0``).
+  This type is only supported on Apple platforms for ``GNU``, ``Clang`` and
+  ``AppleClang`` compilers.
+
+``MSVC``
+  Use the Microsoft linker. This type is only supported on Windows
+  platform for ``MSVC`` and ``Clang`` compiler with ``MSVC`` front-end.