.. If you want to modify sections/contents permanently, you should modify both
   ReleaseNotes.rst and ReleaseNotesTemplate.txt.

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

* Added ``--bp-compression-sort-section=<glob>[=<layout_priority>[=<match_priority>]]``,
  replacing the old coarse ``--bp-compression-sort`` modes with a way to split
  input sections into multiple compression groups, run balanced partitioning
  independently per group, and leave out sections that are poor candidates for
  BP.
  ``layout_priority`` controls group placement order (lower value = placed
  first, default 0). ``match_priority`` resolves conflicts when multiple globs
  match the same section (lower value = higher priority; explicit priority
  beats positional last-match-wins; default: positional). In ELF, the glob
  matches input section names (e.g. ``.text.unlikely.code1``).

* When a ``SECTIONS`` command interleaves relro and non-relro sections, lld now
  emits one ``PT_GNU_RELRO`` segment per contiguous run of relro sections
  instead of reporting a ``not contiguous with other relro sections`` error.

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

* The symbol partition feature has been removed. lld no longer recognizes
  ``SHT_LLVM_SYMPART`` sections, which are now treated as ordinary sections. The
  feature saw no adoption beyond a Chromium experiment that has since been
  retired.

* An OutputSection that has an address expression, and is also assigned
  to a MEMORY region, will now use the address expression in preference
  to the next available location in the MEMORY region. This brings LLD
  in line with GNU ld, but is a change in behavior from previous LLD
  releases.
  
* The default extension for time trace files is now ``.time-trace.json``.

COFF Improvements
-----------------

MinGW Improvements
------------------

* Added ``--push-state`` and ``--pop-state``, offering the same semantics as
  when used with the ELF linker: The state of ``--Bstatic``/``--Bdynamic`` and
  ``--whole-archive`` are pushed onto a stack and popped from it.

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

* ``--bp-compression-sort-section`` now accepts optional layout and match
  priorities (same syntax as ELF). In Mach-O, the glob matches the
  concatenated segment+section name (e.g. ``__TEXT__text``).
* Restructure thunk generation algorithm to be more efficiently create thunks
  (`#193367 <https://github.com/llvm/llvm-project/pull/193367>`_)
* Alphabetically sort LC_LINKER_OPTIONS before processing to match Apple linker behavior
  (`#201604 https://github.com/llvm/llvm-project/pull/201604`)

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

Fixes
#####