===========================
lld |release| Release Notes
===========================
.. contents::
:local:
.. only:: PreRelease
.. warning::
These are in-progress notes for the upcoming LLVM |release| release.
Release notes for previous releases can be found on
`the Download Page <https://releases.llvm.org/download.html>`_.
Introduction
============
This document contains the release notes for the lld linker, release |release|.
Here we describe the status of lld, including major improvements
from the previous release. All lld releases may be downloaded
from the `LLVM releases web site <https://llvm.org/releases/>`_.
Non-comprehensive list of changes in this release
=================================================
ELF Improvements
----------------
* ``--fat-lto-objects`` option is added to support LLVM FatLTO.
Without ``--fat-lto-objects``, LLD will link LLVM FatLTO objects using the
relocatable object file. (`D146778 <https://reviews.llvm.org/D146778>`_)
* ``-Bsymbolic-non-weak`` is added to directly bind non-weak definitions.
(`D158322 <https://reviews.llvm.org/D158322>`_)
* ``--lto-validate-all-vtables-have-type-infos``, which complements
``--lto-whole-program-visibility``, is added to disable unsafe whole-program
devirtualization. ``--lto-known-safe-vtables=<glob>`` can be used
to mark known-safe vtable symbols.
(`D155659 <https://reviews.llvm.org/D155659>`_)
* ``--save-temps --lto-emit-asm`` now derives ELF/asm file names from bitcode file names.
``ld.lld --save-temps a.o d/b.o -o out`` will create ELF relocatable files
``out.lto.a.o``/``d/out.lto.b.o`` instead of ``out1.lto.o``/``out2.lto.o``.
(`#78835 <https://github.com/llvm/llvm-project/pull/78835>`_)
* ``--no-allow-shlib-undefined`` now reports errors for DSO referencing
non-exported definitions.
(`#70769 <https://github.com/llvm/llvm-project/pull/70769>`_)
* common-page-size can now be larger than the system page-size.
(`#57618 <https://github.com/llvm/llvm-project/issues/57618>`_)
* When call graph profile information is available due to instrumentation or
sample PGO, input sections are now sorted using the new ``cdsort`` algorithm,
better than the previous ``hfsort`` algorithm.
(`D152840 <https://reviews.llvm.org/D152840>`_)
* Symbol assignments like ``a = DEFINED(a) ? a : 0;`` are now handled.
(`#65866 <https://github.com/llvm/llvm-project/pull/65866>`_)
* ``OVERLAY`` now supports optional start address and LMA
(`#77272 <https://github.com/llvm/llvm-project/pull/77272>`_)
* Relocations referencing a symbol defined in ``/DISCARD/`` section now lead to
an error.
(`#69295 <https://github.com/llvm/llvm-project/pull/69295>`_)
* For AArch64 MTE, global variable descriptors have been implemented.
(`D152921 <https://reviews.llvm.org/D152921>`_)
* ``R_AARCH64_GOTPCREL32`` is now supported.
(`#72584 <https://github.com/llvm/llvm-project/pull/72584>`_)
* ``R_LARCH_PCREL20_S2``/``R_LARCH_ADD6``/``R_LARCH_CALL36`` and extreme code
model relocations are now supported.
* ``--emit-relocs`` is now supported for RISC-V linker relaxation.
(`D159082 <https://reviews.llvm.org/D159082>`_)
* Call relaxation respects RVC when mixing +c and -c relocatable files.
(`#73977 <https://github.com/llvm/llvm-project/pull/73977>`_)
* ``R_RISCV_GOT32_PCREL`` is now supported.
(`#72587 <https://github.com/llvm/llvm-project/pull/72587>`_)
* ``R_RISCV_SET_ULEB128``/``R_RISCV_SUB_ULEB128`` relocations are now supported.
(`#72610 <https://github.com/llvm/llvm-project/pull/72610>`_)
(`#77261 <https://github.com/llvm/llvm-project/pull/77261>`_)
* RISC-V TLSDESC is now supported.
(`#79239 <https://github.com/llvm/llvm-project/pull/79239>`_)
Breaking changes
----------------
COFF Improvements
-----------------
* Added support for ``--time-trace`` and associated ``--time-trace-granularity``.
This generates a .json profile trace of the linker execution.
(`#68236 <https://github.com/llvm/llvm-project/pull/68236>`_)
* The ``-dependentloadflag`` option was implemented.
(`#71537 <https://github.com/llvm/llvm-project/pull/71537>`_)
* LLD now prefers library paths specified with ``-libpath:`` over the implicitly
detected toolchain paths.
(`#78039 <https://github.com/llvm/llvm-project/pull/78039>`_)
* Added new options ``-lldemit:llvm`` and ``-lldemit:asm`` for getting
the output of LTO compilation as LLVM bitcode or assembly.
(`#66964 <https://github.com/llvm/llvm-project/pull/66964>`_)
(`#67079 <https://github.com/llvm/llvm-project/pull/67079>`_)
* Added a new option ``-build-id`` for generating a ``.buildid`` section
when not generating a PDB. A new symbol ``__buildid`` is generated by
the linker, allowing code to reference the build ID of the binary.
(`#71433 <https://github.com/llvm/llvm-project/pull/71433>`_)
(`#74652 <https://github.com/llvm/llvm-project/pull/74652>`_)
* A new, LLD specific option, ``-lld-allow-duplicate-weak``, was added
for allowing duplicate weak symbols.
(`#68077 <https://github.com/llvm/llvm-project/pull/68077>`_)
* More correctly handle LTO of files that define ``__imp_`` prefixed dllimport
redirections.
(`#70777 <https://github.com/llvm/llvm-project/pull/70777>`_)
(`#71376 <https://github.com/llvm/llvm-project/pull/71376>`_)
(`#72989 <https://github.com/llvm/llvm-project/pull/72989>`_)
* Linking undefined references to weak symbols with LTO now works.
(`#70430 <https://github.com/llvm/llvm-project/pull/70430>`_)
* Use the ``SOURCE_DATE_EPOCH`` environment variable for the PE header and
debug directory timestamps, if neither the ``/Brepro`` nor ``/timestamp:``
options have been specified. This makes the linker output reproducible by
setting this environment variable.
(`#81326 <https://github.com/llvm/llvm-project/pull/81326>`_)
* Lots of incremental work towards supporting linking ARM64EC binaries.
MinGW Improvements
------------------
* Added support for many LTO and ThinLTO options (most LTO options supported
by the ELF driver, that are implemented by the COFF backend as well,
should be supported now).
(`D158412 <https://reviews.llvm.org/D158412>`_)
(`D158887 <https://reviews.llvm.org/D158887>`_)
(`#77387 <https://github.com/llvm/llvm-project/pull/77387>`_)
(`#81475 <https://github.com/llvm/llvm-project/pull/81475>`_)
* LLD no longer tries to autodetect and use library paths from MSVC/WinSDK
installations when run in MinGW mode; that mode of operation shouldn't
ever be needed in MinGW mode, and could be a source of unexpected
behaviours.
(`D144084 <https://reviews.llvm.org/D144084>`_)
* The ``--icf=safe`` option now works as expected; it was previously a no-op.
(`#70037 <https://github.com/llvm/llvm-project/pull/70037>`_)
* The strip flags ``-S`` and ``-s`` now can be used to strip out DWARF debug
info and symbol tables while emitting a PDB debug info file.
(`#75181 <https://github.com/llvm/llvm-project/pull/75181>`_)
* The option ``--dll`` is handled as an alias for the ``--shared`` option.
(`#68575 <https://github.com/llvm/llvm-project/pull/68575>`_)
* The option ``--sort-common`` is ignored now.
(`#66336 <https://github.com/llvm/llvm-project/pull/66336>`_)
MachO Improvements
------------------
WebAssembly Improvements
------------------------
* Indexes are no longer required on archive files. Instead symbol information
is read from object files within the archive. This matches the behaviour of
the ELF linker.
Fixes
#####