mirror of
https://github.com/Kitware/CMake.git
synced 2026-05-04 05:10:10 -05:00
Merge topic 'doc-linker-vars'
6ba2bbc0f3Help: Restructure and improve LINKER_TYPE docsc39bc6e412Help: CMAKE_<LANG>_USING_LINKER_<TYPE> can be a list of flags1c7ccefd83Help: Add custom linker example for CMAKE_<LANG>_USING_LINKER_<TYPE>aecea7b28bHelp: Grammar, typos and wording improvements for linker variables5b21897c6eHelp: Remove stray formatting for try_compile() LINKER_LANGUAGE keyword Acked-by: Kitware Robot <kwrobot@kitware.com> Merge-request: !9362
This commit is contained in:
Brad King
@@ -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.
|
||||
|
||||
@@ -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
|
||||
=============================== ===============================================
|
||||
|
||||
@@ -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
|
||||
|
||||
@@ -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)
|
||||
|
||||
@@ -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
|
||||
|
||||
@@ -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
|
||||
|
||||
Reference in New Issue
Block a user