lld/docs/ReleaseNotes.rst

===========================
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
----------------

* ``-z nosectionheader`` has been implemented to omit the section header table.
  The operation is similar to ``llvm-objcopy --strip-sections``.
  (`#101286 <https://github.com/llvm/llvm-project/pull/101286>`_)
* ``--randomize-section-padding=<seed>`` is introduced to insert random padding
  between input sections and at the start of each segment. This can be used to
  control measurement bias in A/B experiments.
  (`#117653 <https://github.com/llvm/llvm-project/pull/117653>`_)
* The reproduce tarball created with ``--reproduce=`` now excludes directories
  specified in the ``--dependency-file`` argument (used by Ninja). This
  resolves an error where non-existent directories could cause issues when
  invoking ``ld.lld @response.txt``.
* ``--symbol-ordering-file=`` and call graph profile can now be used together.
* When ``--call-graph-ordering-file=`` is specified, ``.llvm.call-graph-profile``
  sections in relocatable files are no longer used.
* ``--lto-basic-block-sections=labels`` is deprecated in favor of
  ``--lto-basic-block-address-map``.
  (`#110697 <https://github.com/llvm/llvm-project/pull/110697>`_)
* In non-relocatable links, a ``.note.GNU-stack`` section with the
  ``SHF_EXECINSTR`` flag is now rejected unless ``-z execstack`` is specified.
  (`#124068 <https://github.com/llvm/llvm-project/pull/124068>`_)
* In relocatable links, the ``sh_entsize`` member of a ``SHF_MERGE`` section
  with relocations is now respected in the output.
* Quoted names can now be used in output section phdr, memory region names,
  ``OVERLAY``, the LHS of ``--defsym``, and ``INSERT AFTER``.
* Section ``CLASS`` linker script syntax binds input sections to named classes,
  which are referenced later one or more times. This provides access to the
  automatic spilling mechanism of `--enable-non-contiguous-regions` without
  globally changing the semantics of section matching. It also independently
  increases the expressive power of linker scripts.
  (`#95323 <https://github.com/llvm/llvm-project/pull/95323>`_)
* ``INCLUDE`` cycle detection has been fixed. A linker script can now be
  included twice.
* The ``archivename:`` syntax when matching input sections is now supported.
  (`#119293 <https://github.com/llvm/llvm-project/pull/119293>`_)
* To support Arm v6-M, short thunks using B.w are no longer generated.
  (`#118111 <https://github.com/llvm/llvm-project/pull/118111>`_)
* For AArch64, BTI-aware long branch thunks can now be created to a destination
  function without a BTI instruction.
  (`#108989 <https://github.com/llvm/llvm-project/pull/108989>`_)
  (`#116402 <https://github.com/llvm/llvm-project/pull/116402>`_)
* Relocations related to GOT and TLSDESC for the AArch64 Pointer Authentication ABI
  are now supported.
* Supported relocation types for x86-64 target:
  * ``R_X86_64_CODE_4_GOTPCRELX`` (`#109783 <https://github.com/llvm/llvm-project/pull/109783>`_) (`#116737 <https://github.com/llvm/llvm-project/pull/116737>`_)
  * ``R_X86_64_CODE_4_GOTTPOFF`` (`#116634 <https://github.com/llvm/llvm-project/pull/116634>`_)
  * ``R_X86_64_CODE_4_GOTPC32_TLSDESC`` (`#116909 <https://github.com/llvm/llvm-project/pull/116909>`_)
  * ``R_X86_64_CODE_6_GOTTPOFF``  (`#117675 <https://github.com/llvm/llvm-project/pull/117675>`_)
* Supported relocation types for LoongArch target: ``R_LARCH_TLS_{LD,GD,DESC}_PCREL20_S2``.
  (`#100105 <https://github.com/llvm/llvm-project/pull/100105>`_)

* The default Hexagon architecture version in ELF object files produced by
  lld is changed to v68. This change is only effective when the version is
  not provided in the command line by the user and cannot be inferred from
  inputs.

Breaking changes
----------------

* Removed support for the (deprecated) `R_RISCV_RVC_LUI` relocation. This
  was a binutils-internal relocation used during relaxation, and was not
  emitted by compilers/assemblers.

COFF Improvements
-----------------
* ``/includeglob`` has been implemented to match the behavior of ``--undefined-glob`` available for ELF.
* ``/lldsavetemps`` allows saving select intermediate LTO compilation results (e.g. resolution, preopt, promote, internalize, import, opt, precodegen, prelink, combinedindex).
* ``/machine:arm64ec`` support completed, enabling the linking of ARM64EC images.
* COFF weak anti-dependency alias symbols are now supported.

MinGW Improvements
------------------
* ``--undefined-glob`` is now supported by translating into the ``/includeglob`` flag.

MachO Improvements
------------------

WebAssembly Improvements
------------------------

Fixes
#####