From 5b21897c6e1576593c8bb01ba08792c1bf9ff15d Mon Sep 17 00:00:00 2001 From: Craig Scott Date: Fri, 22 Mar 2024 20:58:32 +1100 Subject: Help: Remove stray formatting for try_compile() LINKER_LANGUAGE keyword --- Help/command/try_compile.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Help/command/try_compile.rst b/Help/command/try_compile.rst index f44a4e8..5021851 100644 --- a/Help/command/try_compile.rst +++ b/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 ``` +``LINKER_LANGUAGE `` .. versionadded:: 3.29 Specify the :prop_tgt:`LINKER_LANGUAGE` target property of the generated -- cgit v0.12 From aecea7b28bbf2e7651c7d01af496f5f1c498364d Mon Sep 17 00:00:00 2001 From: Craig Scott Date: Tue, 26 Mar 2024 08:02:46 +1100 Subject: Help: Grammar, typos and wording improvements for linker variables --- ...CMAKE_LANG_COMPILER_LINKER_FRONTEND_VARIANT.rst | 11 ++++------ Help/variable/CMAKE_LANG_COMPILER_LINKER_ID.rst | 4 ++-- Help/variable/CMAKE_LANG_USING_LINKER_MODE.rst | 4 ++-- Help/variable/CMAKE_LANG_USING_LINKER_TYPE.rst | 24 +++++++++++----------- Help/variable/CMAKE_LINKER_TYPE.rst | 8 ++++---- 5 files changed, 24 insertions(+), 27 deletions(-) diff --git a/Help/variable/CMAKE_LANG_COMPILER_LINKER_FRONTEND_VARIANT.rst b/Help/variable/CMAKE_LANG_COMPILER_LINKER_FRONTEND_VARIANT.rst index d7d028a..735375c 100644 --- a/Help/variable/CMAKE_LANG_COMPILER_LINKER_FRONTEND_VARIANT.rst +++ b/Help/variable/CMAKE_LANG_COMPILER_LINKER_FRONTEND_VARIANT.rst @@ -6,16 +6,13 @@ CMAKE__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__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 index 0607aea..a57fd33 100644 --- a/Help/variable/CMAKE_LANG_COMPILER_LINKER_ID.rst +++ b/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 =============================== =============================================== diff --git a/Help/variable/CMAKE_LANG_USING_LINKER_MODE.rst b/Help/variable/CMAKE_LANG_USING_LINKER_MODE.rst index c9b6779..66ce26b 100644 --- a/Help/variable/CMAKE_LANG_USING_LINKER_MODE.rst +++ b/Help/variable/CMAKE_LANG_USING_LINKER_MODE.rst @@ -3,8 +3,8 @@ CMAKE__USING_LINKER_MODE .. versionadded:: 3.29 -This variable specify what is the type of data stored in variable - :variable:`CMAKE__USING_LINKER_`. There are two possible values: +This controls how the value of the :variable:`CMAKE__USING_LINKER_` +variable should be interpreted. The supported linker mode values are: ``FLAG`` :variable:`CMAKE__USING_LINKER_` holds compiler flags. This is diff --git a/Help/variable/CMAKE_LANG_USING_LINKER_TYPE.rst b/Help/variable/CMAKE_LANG_USING_LINKER_TYPE.rst index d4714c3..88c0335 100644 --- a/Help/variable/CMAKE_LANG_USING_LINKER_TYPE.rst +++ b/Help/variable/CMAKE_LANG_USING_LINKER_TYPE.rst @@ -3,32 +3,32 @@ CMAKE__USING_LINKER_ .. 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__USING_LINKER_MODE`. +This variable defines how to specify the ```` 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__USING_LINKER_MODE` variable, +``CMAKE__USING_LINKER_`` 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__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 diff --git a/Help/variable/CMAKE_LINKER_TYPE.rst b/Help/variable/CMAKE_LINKER_TYPE.rst index 17ea947..ac72c38 100644 --- a/Help/variable/CMAKE_LINKER_TYPE.rst +++ b/Help/variable/CMAKE_LINKER_TYPE.rst @@ -9,10 +9,10 @@ Specify which linker will be used for the link step. 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 -- cgit v0.12 From 1c7ccefd83784f113768eaea085bce67f3c26fba Mon Sep 17 00:00:00 2001 From: Craig Scott Date: Fri, 22 Mar 2024 21:08:50 +1100 Subject: Help: Add custom linker example for CMAKE__USING_LINKER_ --- Help/variable/CMAKE_LANG_USING_LINKER_TYPE.rst | 8 ++++++++ 1 file changed, 8 insertions(+) diff --git a/Help/variable/CMAKE_LANG_USING_LINKER_TYPE.rst b/Help/variable/CMAKE_LANG_USING_LINKER_TYPE.rst index 88c0335..1cf7d28 100644 --- a/Help/variable/CMAKE_LANG_USING_LINKER_TYPE.rst +++ b/Help/variable/CMAKE_LANG_USING_LINKER_TYPE.rst @@ -34,3 +34,11 @@ compiler frontend: 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) -- cgit v0.12 From c39bc6e412f3ee7e28844b5ecaa0186790ce78e6 Mon Sep 17 00:00:00 2001 From: Craig Scott Date: Fri, 22 Mar 2024 21:10:56 +1100 Subject: Help: CMAKE__USING_LINKER_ can be a list of flags --- Help/variable/CMAKE_LANG_USING_LINKER_MODE.rst | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/Help/variable/CMAKE_LANG_USING_LINKER_MODE.rst b/Help/variable/CMAKE_LANG_USING_LINKER_MODE.rst index 66ce26b..bfed407 100644 --- a/Help/variable/CMAKE_LANG_USING_LINKER_MODE.rst +++ b/Help/variable/CMAKE_LANG_USING_LINKER_MODE.rst @@ -7,8 +7,10 @@ This controls how the value of the :variable:`CMAKE__USING_LINKER_` variable should be interpreted. The supported linker mode values are: ``FLAG`` - :variable:`CMAKE__USING_LINKER_` holds compiler flags. This is - the default. + :variable:`CMAKE__USING_LINKER_` holds a + :ref:`semicolon-separated list ` of flags to be passed + to the compiler frontend. This is also the default behavior if + ``CMAKE__USING_LINKER_MODE`` is not set. ``TOOL`` :variable:`CMAKE__USING_LINKER_` holds the path to the linker -- cgit v0.12 From 6ba2bbc0f34eb2a0b2dac2eb84755a551fa34203 Mon Sep 17 00:00:00 2001 From: Craig Scott Date: Fri, 22 Mar 2024 21:11:50 +1100 Subject: Help: Restructure and improve LINKER_TYPE docs --- Help/prop_tgt/LINKER_TYPE.rst | 24 ++++++------ Help/variable/CMAKE_LINKER_TYPE.rst | 4 -- Help/variable/LINKER_PREDEFINED_TYPES.txt | 61 +++++++++++++++++-------------- 3 files changed, 46 insertions(+), 43 deletions(-) diff --git a/Help/prop_tgt/LINKER_TYPE.rst b/Help/prop_tgt/LINKER_TYPE.rst index 90a663d..0a016fe 100644 --- a/Help/prop_tgt/LINKER_TYPE.rst +++ b/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 `. +.. 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__USING_LINKER_` 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__USING_LINKER_` with ```` having the value -``LLD``. +The command line options that will be passed to the toolchain will be provided +by the ``CMAKE__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. diff --git a/Help/variable/CMAKE_LINKER_TYPE.rst b/Help/variable/CMAKE_LINKER_TYPE.rst index ac72c38..e2989ec 100644 --- a/Help/variable/CMAKE_LINKER_TYPE.rst +++ b/Help/variable/CMAKE_LINKER_TYPE.rst @@ -5,10 +5,6 @@ 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` property on each target created by a call to :command:`add_library` or :command:`add_executable`. It is meaningful only for targets having a diff --git a/Help/variable/LINKER_PREDEFINED_TYPES.txt b/Help/variable/LINKER_PREDEFINED_TYPES.txt index e8cb19f..69ac1c2 100644 --- a/Help/variable/LINKER_PREDEFINED_TYPES.txt +++ b/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 `_. 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 `_. 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 -- cgit v0.12