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