docs/ReleaseNotes.rst

=======================
lld 5.0.0 Release Notes
=======================

.. contents::
    :local:

Introduction
============

lld is a linker from the LLVM project. It supports ELF (Unix), COFF (Windows)
and Mach-O (macOS), and it is generally faster than the GNU bfd or gold linkers
or the MSVC linker.

lld is designed to be a drop-in replacement for the system linkers, so that
users don't need to change their build systems other than swapping the linker
command.

All lld releases may be downloaded from the `LLVM releases web site
<http://llvm.org/releases/>`_.

Non-comprehensive list of changes in this release
=================================================

ELF Improvements
----------------

* First and foremost, a lot of compatibility issues and bugs have been fixed.
  Linker script support has significantly improved. As a result, we believe you
  are very likely to be able to link your programs with lld without experiencing
  any problem now.

* Error message format has changed in order to improve readability.
  Traditionally, linker's error messages are concise and arguably too terse.
  This is an example of lld 4.0.0's error message (they are actually in one line)::

    /ssd/clang/bin/ld.lld: error: /ssd/llvm-project/lld/ELF/Writer.cpp:207:
      undefined symbol 'lld::elf::EhFrameSection::addSection()'

  It is not easy to read because too much information is packed into a single line
  and the embedded text, particularly a symbol name, is sometimes too long.
  In lld 5.0.0, we use more vertical space to print out error messages in a more
  structured manner like this::

    bin/ld.lld: error: undefined symbol: lld::elf::EhFrameSection::addSection()
    >>> Referenced by Writer.cpp:207 (/ssd/llvm-project/lld/ELF/Writer.cpp:207)
    >>>               Writer.cpp.o in archive lib/liblldELF.a

  As a bonus, the new error message contains source code location of the error
  if it is available from debug info.

* ``./configure`` scripts generated by GNU autoconf determines whether a linker
  supports modern GNU-compatible features or not by searching for "GNU" in the
  ``--help`` message. To be compatible with the scripts, we decided to add a
  string "(compatible with GNU linkers)" to our ``--help`` message. This is a
  hack, but just like the web browser's User-Agent string (which everyone still
  claim they are "Mozilla/5.0"), we had no choice other than doing this to claim
  that we accept GNU-compatible options.

* The ``-Map`` option is added. The option is to make the linker to print out how
  input files are mapped to the output file. Here is an example::

    Address          Size             Align Out     In      Symbol
    00000000016d84d8 00000000008f8f50     8 .eh_frame
    00000000016d84d8 00000000008f8f50     8         <internal>:(.eh_frame)
    0000000001fd2000 00000000034b3bd0    16 .text
    0000000001fd2000 000000000000002a     1         /usr/lib/x86_64-linux-gnu/crt1.o:(.text)
    0000000001fd2000 0000000000000000     0                 _start
    0000000001fd202a 0000000000000000     1         /usr/lib/x86_64-linux-gnu/crti.o:(.text)
    0000000001fd2030 00000000000000bd    16         /usr/lib/gcc/x86_64-linux-gnu/4.8/crtbegin.o:(.text)
    0000000001fd2030 0000000000000000     0                 deregister_tm_clones
    0000000001fd2060 0000000000000000     0                 register_tm_clones

  This format is not the same as GNU linkers as our linker internal data
  structure is different from them but contains the same amount of information
  and should be more readable than their outputs.

  As with other lld features, the ``-Map`` option is designed with speed in mind.
  The option would generate a hundred megabyte text file if you link a large
  program with it. lld can usually do that in a few seconds, and it is generally
  a few times faster than the GNU gold's ``-Map`` option.

* lld's ``--gdb-index`` option used to be slow, but we sped it up so that it is
  at least as fast as the GNU gold.

* Some nonstandard relocations, such as R_X86_64_8 or R_X86_64_16, are supported.
  They are not used for 32/64-bit applications, but some 16-bit bootloaders need
  them.

* Paddings in executable text sections are now filled with trap instructions
  (such as INT3) instead of being left as null bytes. This change improves
  disassembler outputs because it now prints out trap instructions instead of
  trying to decode 0x00 as an instruction. It also makes debugging of some type
  of program easier because when the control reaches a padding, the program
  immediately raises an error.

* The following options are added: ``-M``, ``-Map``,
  ``-compress-debug-sections``, ``-emit-relocs``,
  ``-error-unresolved-symbols``, ``-exclude-libs``, ``-filter``,
  ``-no-dynamic-linker``, ``-no-export-dynamic``, ``-no-fatal-warnings``,
  ``-print-map``, ``-warn-unresolved-symbols``, ``-z nocopyreloc``,
  ``-z notext``, ``-z rodynamic``


Contributors to lld 5.0
=======================

We had 63 individuals contribute to lld 5.0. Thank you so much!

- Adrian McCarthy
- Alberto Magni
- Alexander Richardson
- Andre Vieira
- Andrew Ng
- Anton Korobeynikov
- Bob Haarman
- David Blaikie
- Davide Italiano
- David L. Jones
- Dmitry Mikulin
- Ed Maste
- Ed Schouten
- Eric Beckmann
- Eric Fiselier
- Eugene Leviant
- Evgeniy Stepanov
- Galina Kistanova
- George Rimar
- Hans Wennborg
- Igor Kudrin
- Ismail Donmez
- Jake Ehrlich
- James Henderson
- Joel Jones
- Jon Chesterfield
- Kamil Rytarowski
- Kevin Enderby
- Konstantin Zhuravlyov
- Kyungwoo Lee
- Leslie Zhai
- Mark Kettenis
- Martell Malone
- Martin Storsjo
- Meador Inge
- Mehdi Amini
- Michal Gorny
- NAKAMURA Takumi
- Paul Robinson
- Pavel Labath
- Petar Jovanovic
- Peter Collingbourne
- Peter Smith
- Petr Hosek
- Rafael Espindola
- Reid Kleckner
- Richard Smith
- Robert Clarke
- Rui Ueyama
- Saleem Abdulrasool
- Sam Clegg
- Sean Eveson
- Sean Silva
- Shankar Easwaran
- Shoaib Meenai
- Simon Atanasyan
- Simon Dardis
- Simon Tatham
- Sylvestre Ledru
- Tom Stellard
- Vitaly Buka
- Yuka Takahashi
- Zachary Turner