Merge topic 'doc-linker-vars' into release-3.29

6ba2bbc0f3 Help: Restructure and improve LINKER_TYPE docs
c39bc6e412 Help: CMAKE_<LANG>_USING_LINKER_<TYPE> can be a list of flags
1c7ccefd83 Help: Add custom linker example for CMAKE_<LANG>_USING_LINKER_<TYPE>
aecea7b28b Help: Grammar, typos and wording improvements for linker variables
5b21897c6e Help: Remove stray formatting for try_compile() LINKER_LANGUAGE keyword

Acked-by: Kitware Robot <[email protected]>
Merge-request: !9362

Help/command/try_compile.rst

@@ -188,7 +188,7 @@ The options for the above signatures are:
   set the :prop_tgt:`STATIC_LIBRARY_OPTIONS` target property in the generated
   project, depending on the :variable:`CMAKE_TRY_COMPILE_TARGET_TYPE` variable.
 
-``LINKER_LANGUAGE <lang>```
+``LINKER_LANGUAGE <lang>``
   .. versionadded:: 3.29
 
   Specify the :prop_tgt:`LINKER_LANGUAGE` target property of the generated

Help/prop_tgt/LINKER_TYPE.rst

@@ -6,21 +6,23 @@ LINKER_TYPE
 Specify which linker will be used for the link step. The property value may use
 :manual:`generator expressions <cmake-generator-expressions(7)>`.
 
+.. include:: ../variable/LINKER_PREDEFINED_TYPES.txt
+
+This property is not supported on :generator:`Green Hills MULTI` and
+:generator:`Visual Studio 9 2008` generators.
+
+The implementation details for the selected linker will be provided by the
+:variable:`CMAKE_<LANG>_USING_LINKER_<TYPE>` variable. For example:
+
 .. code-block:: cmake
 
   add_library(lib1 SHARED ...)
   set_property(TARGET lib1 PROPERTY LINKER_TYPE LLD)
 
 This specifies that ``lib1`` should use linker type ``LLD`` for the link step.
-The implementation details will be provided by the variable
-:variable:`CMAKE_<LANG>_USING_LINKER_<TYPE>` with ``<TYPE>`` having the value
-``LLD``.
+The command line options that will be passed to the toolchain will be provided
+by the ``CMAKE_<LANG>_USING_LINKER_LLD`` variable.
 
-This property is not supported on :generator:`Green Hills MULTI` and
-:generator:`Visual Studio 9 2008` generators.
-
-.. note::
-  It is assumed that the linker specified is fully compatible with the standard
-  one. CMake will not do any options translation.
-
-.. include:: ../variable/LINKER_PREDEFINED_TYPES.txt
+Note that the linker would typically be set using :variable:`CMAKE_LINKER_TYPE`
+for the whole build rather than setting the ``LINKER_TYPE`` property on
+individual targets.

Help/variable/CMAKE_LANG_COMPILER_LINKER_FRONTEND_VARIANT.rst

@@ -6,16 +6,13 @@ CMAKE_<LANG>_COMPILER_LINKER_FRONTEND_VARIANT
 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
+line options.  For example, ``LLVM 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.

Help/variable/CMAKE_LANG_COMPILER_LINKER_ID.rst

@@ -17,8 +17,8 @@ Value                           Name
                                 ``bfd``)
 ``GNUgold``                     `GNU Binutils - gold linker`_
 ``MSVC``                        `Microsoft Visual Studio`_
-``MOLD``                        `mold: A Modern Linker`_ or, on Apple, `sold`_
-                                linker
+``MOLD``                        `mold: A Modern Linker`_, or on Apple the
+                                `sold`_ linker
 ``AIX``                         AIX system linker
 ``Solaris``                     SunOS system linker
 =============================== ===============================================

Help/variable/CMAKE_LANG_USING_LINKER_MODE.rst

@@ -3,12 +3,14 @@ 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:
+This controls how the value of the :variable:`CMAKE_<LANG>_USING_LINKER_<TYPE>`
+variable should be interpreted. The supported linker mode values are:
 
 ``FLAG``
-  :variable:`CMAKE_<LANG>_USING_LINKER_<TYPE>` holds compiler flags. This is
-  the default.
+  :variable:`CMAKE_<LANG>_USING_LINKER_<TYPE>` holds a
+  :ref:`semicolon-separated list <CMake Language Lists>` of flags to be passed
+  to the compiler frontend.  This is also the default behavior if
+  ``CMAKE_<LANG>_USING_LINKER_MODE`` is not set.
 
 ``TOOL``
   :variable:`CMAKE_<LANG>_USING_LINKER_<TYPE>` holds the path to the linker

Help/variable/CMAKE_LANG_USING_LINKER_TYPE.rst

@@ -3,34 +3,42 @@ 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`.
+This variable defines how to specify the ``<TYPE>`` linker for the link step,
+as controlled by the :variable:`CMAKE_LINKER_TYPE` variable or the
+:prop_tgt:`LINKER_TYPE` target property. Depending on the value of the
+:variable:`CMAKE_<LANG>_USING_LINKER_MODE` variable,
+``CMAKE_<LANG>_USING_LINKER_<TYPE>`` can hold compiler flags for the link step,
+or flags to be given directly to the linker tool.
 
 .. note::
 
-  The specified linker tool is expected to be accessible through
-  the ``PATH`` environment variable, particularly when the
-  :variable:`CMAKE_<LANG>_USING_LINKER_MODE` variable is set to ``FLAG``.
+  The specified linker tool is generally expected to be accessible through
+  the ``PATH`` environment variable.
 
-For example, to specify the ``LLVM`` linker for ``GNU`` compilers, we have:
+For example, the ``LLD`` linker for ``GNU`` compilers is defined like so:
 
 .. code-block:: cmake
 
   set(CMAKE_C_USING_LINKER_LLD "-fuse-ld=lld")
 
-Or on ``Windows`` platform, for ``Clang`` compilers simulating ``MSVC``, we
-have:
+On the ``Windows`` platform with ``Clang`` compilers simulating ``MSVC``:
 
 .. 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:
+And for the ``MSVC`` compiler, the linker is invoked directly, not via the
+compiler frontend:
 
 .. code-block:: cmake
 
   set(CMAKE_C_USING_LINKER_LLD "/path/to/lld-link.exe")
   set(CMAKE_C_USING_LINKER_MODE TOOL)
+
+A custom linker type can also be defined, usually in a toolchain file:
+
+.. code-block:: cmake
+
+  set(CMAKE_LINKER_TYPE lld_launcher)
+  set(CMAKE_C_USING_LINKER_lld_launcher "-fuse-ld=/path/to/lld-launcher.sh")
+  set(CMAKE_C_USING_LINKER_MODE FLAG)

Help/variable/CMAKE_LINKER_TYPE.rst

@@ -5,14 +5,10 @@ CMAKE_LINKER_TYPE
 
 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`
+This variable is used to initialize the :prop_tgt:`LINKER_TYPE` property
+on each target created by a call to :command:`add_library` or
+:command:`add_executable`.  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

Help/variable/LINKER_PREDEFINED_TYPES.txt

@@ -1,59 +1,64 @@
+.. note::
+  It is assumed that the linker specified is fully compatible with the default
+  one the compiler would normally invoke. CMake will not do any option
+  translation.
+
 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.
+  This type corresponds to standard linking, essentially equivalent to the
+  :prop_tgt:`LINKER_TYPE` target property not being set at all.
 
 ``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:
+  Use the standard linker provided by the platform or toolchain. For example,
+  this implies the Microsoft linker for all ``MSVC``-compatible compilers.
+  This type is supported for the following platform-compiler combinations:
 
-  * Linux, for ``GNU``, ``Clang``, ``LLVMFlang`` and ``NVIDIA`` compilers.
-  * All Apple variants for ``AppleClang``, ``Clang`` and ``GNU`` compilers.
-  * Windows, for ``MSVC``, ``GNU``, ``Clang`` and ``NVIDIA`` compilers.
+  * Linux: ``GNU``, ``Clang``, ``LLVMFlang`` and ``NVIDIA`` compilers.
+  * All Apple variants: ``AppleClang``, ``Clang`` and ``GNU`` compilers.
+  * Windows: ``MSVC``, ``GNU``, ``Clang`` and ``NVIDIA`` compilers.
 
 ``LLD``
   Use the ``LLVM`` linker. This type is supported for the following
-  platforms/compilers:
+  platform-compiler combinations:
 
-  * Linux, for ``GNU``, ``Clang``, ``LLVMFlang`` 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.
+  * Linux: ``GNU``, ``Clang``, ``LLVMFlang`` and ``NVIDIA`` compilers.
+  * All Apple variants: ``Clang`` and ``AppleClang`` compilers.
+  * Windows: ``GNU``, ``Clang``, ``Clang`` compilers with ``GNU`` front-end,
+    ``MSVC`` and ``NVIDIA`` compilers with ``MSVC`` front-end.
 
 ``BFD``
   Use the ``GNU`` linker.  This type is supported for the following
-  platforms/compilers:
+  platform-compiler combinations:
 
-  * Linux, for ``GNU``, ``Clang``, ``LLVMFlang`` and ``NVIDIA`` compilers.
-  * Windows, for ``GNU``, ``Clang`` compilers with ``GNU`` front-end.
+  * Linux: ``GNU``, ``Clang``, ``LLVMFlang`` and ``NVIDIA`` compilers.
+  * Windows: ``GNU``, ``Clang`` compilers with ``GNU`` front-end.
 
 ``GOLD``
-  Supported on Linux platform for ``GNU``, ``Clang``, ``LLVMFlang`` and
+  Supported on Linux platform with ``GNU``, ``Clang``, ``LLVMFlang`` and
   ``NVIDIA`` compilers.
 
 ``MOLD``
   Use the `mold linker <https://github.com/rui314/mold>`_. This type is
-  supported on the following platforms:
+  supported on the following platform-compiler combinations:
 
-  * Linux platform for ``GNU``, ``Clang``, ``LLVMFlang`` and ``NVIDIA``
-    compilers.
-  * All Apple variants for ``Clang`` and ``AppleClang`` compilers as an
-    alias to ``SOLD``.
+  * Linux: ``GNU``, ``Clang``, ``LLVMFlang`` and ``NVIDIA`` compilers.
+  * All Apple variants: ``Clang`` and ``AppleClang`` compilers (acts as an
+    alias to the `sold linker`_).
 
 ``SOLD``
-  Use the `sold linker <https://github.com/bluewhalesystems/sold>`_. This type
-  is only supported on Apple platforms for ``Clang`` and ``AppleClang``
-  compilers.
+  Use the `sold linker`_. This type is only supported on Apple platforms
+  with ``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
+  This type is only supported on Apple platforms with ``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.
+  Use the Microsoft linker. This type is only supported on the Windows
+  platform with ``MSVC`` and ``Clang`` compiler with ``MSVC`` front-end.
+
+.. _sold linker: https://github.com/bluewhalesystems/sold