lld/docs/index.rst

   1 LLD - The LLVM Linker
   2 =====================
   3
   4 LLD is a linker from the LLVM project that is a drop-in replacement
   5 for system linkers and runs much faster than them. It also provides
   6 features that are useful for toolchain developers.
   7
   8 The linker supports ELF (Unix), PE/COFF (Windows), Mach-O (macOS) and
   9 WebAssembly in descending order of completeness. Internally, LLD consists of
  10 several different linkers. The ELF port is the one that will be described in
  11 this document. The PE/COFF port is complete, including
  12 Windows debug info (PDB) support. The WebAssembly port is still a work in
  13 progress (See :doc:`WebAssembly`).
  14
  15 Features
  16 --------
  17
  18 - LLD is a drop-in replacement for the GNU linkers that accepts the
  19   same command line arguments and linker scripts as GNU.
  20
  21 - LLD is very fast. When you link a large program on a multicore
  22   machine, you can expect that LLD runs more than twice as fast as the GNU
  23   gold linker. Your mileage may vary, though.
  24
  25 - It supports various CPUs/ABIs including AArch64, AMDGPU, ARM, Hexagon,
  26   LoongArch, MIPS 32/64 big/little-endian, PowerPC, PowerPC64, RISC-V,
  27   SPARC V9, x86-32 and x86-64. Among these, AArch64, ARM (>= v4), LoongArch,
  28   PowerPC, PowerPC64, RISC-V, x86-32 and x86-64 have production quality.
  29   MIPS seems decent too.
  30
  31 - It is always a cross-linker, meaning that it always supports all the
  32   above targets however it was built. In fact, we don't provide a
  33   build-time option to enable/disable each target. This should make it
  34   easy to use our linker as part of a cross-compile toolchain.
  35
  36 - You can embed LLD in your program to eliminate dependencies on
  37   external linkers. All you have to do is to construct object files
  38   and command line arguments just like you would do to invoke an
  39   external linker and then call the linker's main function,
  40   ``lld::lldMain``, from your code.
  41
  42 - It is small. We are using LLVM libObject library to read from object
  43   files, so it is not a completely fair comparison, but as of February
  44   2017, LLD/ELF consists only of 21k lines of C++ code while GNU gold
  45   consists of 198k lines of C++ code.
  46
  47 - Link-time optimization (LTO) is supported by default. Essentially,
  48   all you have to do to do LTO is to pass the ``-flto`` option to clang.
  49   Then clang creates object files not in the native object file format
  50   but in LLVM bitcode format. LLD reads bitcode object files, compile
  51   them using LLVM and emit an output file. Because in this way LLD can
  52   see the entire program, it can do the whole program optimization.
  53
  54 - Some very old features for ancient Unix systems (pre-90s or even
  55   before that) have been removed. Some default settings have been
  56   tuned for the 21st century. For example, the stack is marked as
  57   non-executable by default to tighten security.
  58
  59 Performance
  60 -----------
  61
  62 This is a link time comparison on a 2-socket 20-core 40-thread Xeon
  63 E5-2680 2.80 GHz machine with an SSD drive. We ran gold and lld with
  64 or without multi-threading support. To disable multi-threading, we
  65 added ``-no-threads`` to the command lines.
  66
  67 ============  ===========  ============  ====================  ==================  ===============  =============
  68 Program       Output size  GNU ld        GNU gold w/o threads  GNU gold w/threads  lld w/o threads  lld w/threads
  69 ffmpeg dbg    92 MiB       1.72s         1.16s                 1.01s               0.60s            0.35s
  70 mysqld dbg    154 MiB      8.50s         2.96s                 2.68s               1.06s            0.68s
  71 clang dbg     1.67 GiB     104.03s       34.18s                23.49s              14.82s           5.28s
  72 chromium dbg  1.14 GiB     209.05s [1]_  64.70s                60.82s              27.60s           16.70s
  73 ============  ===========  ============  ====================  ==================  ===============  =============
  74
  75 As you can see, lld is significantly faster than GNU linkers.
  76 Note that this is just a benchmark result of our environment.
  77 Depending on number of available cores, available amount of memory or
  78 disk latency/throughput, your results may vary.
  79
  80 .. [1] Since GNU ld doesn't support the ``-icf=all`` and
  81        ``-gdb-index`` options, we removed them from the command line
  82        for GNU ld. GNU ld would have been slower than this if it had
  83        these options.
  84
  85 Build
  86 -----
  87
  88 If you have already checked out LLVM using SVN, you can check out LLD
  89 under ``tools`` directory just like you probably did for clang. For the
  90 details, see `Getting Started with the LLVM System
  91 <https://llvm.org/docs/GettingStarted.html>`_.
  92
  93 If you haven't checked out LLVM, the easiest way to build LLD is to
  94 check out the entire LLVM projects/sub-projects from a git mirror and
  95 build that tree. You need `cmake` and of course a C++ compiler.
  96
  97 .. code-block:: console
  98
  99   $ git clone https://github.com/llvm/llvm-project llvm-project
 100   $ mkdir build
 101   $ cd build
 102   $ cmake -DCMAKE_BUILD_TYPE=Release -DLLVM_ENABLE_PROJECTS=lld -DCMAKE_INSTALL_PREFIX=/usr/local ../llvm-project/llvm
 103   $ make install
 104
 105 Using LLD
 106 ---------
 107
 108 LLD is installed as ``ld.lld``. On Unix, linkers are invoked by
 109 compiler drivers, so you are not expected to use that command
 110 directly. There are a few ways to tell compiler drivers to use ld.lld
 111 instead of the default linker.
 112
 113 The easiest way to do that is to overwrite the default linker. After
 114 installing LLD to somewhere on your disk, you can create a symbolic
 115 link by doing ``ln -s /path/to/ld.lld /usr/bin/ld`` so that
 116 ``/usr/bin/ld`` is resolved to LLD.
 117
 118 If you don't want to change the system setting, you can use clang's
 119 ``-fuse-ld`` option. In this way, you want to set ``-fuse-ld=lld`` to
 120 LDFLAGS when building your programs.
 121
 122 LLD leaves its name and version number to a ``.comment`` section in an
 123 output. If you are in doubt whether you are successfully using LLD or
 124 not, run ``readelf --string-dump .comment <output-file>`` and examine the
 125 output. If the string "Linker: LLD" is included in the output, you are
 126 using LLD.
 127
 128 History
 129 -------
 130
 131 Here is a brief project history of the ELF and COFF ports.
 132
 133 - May 2015: We decided to rewrite the COFF linker and did that.
 134   Noticed that the new linker is much faster than the MSVC linker.
 135
 136 - July 2015: The new ELF port was developed based on the COFF linker
 137   architecture.
 138
 139 - September 2015: The first patches to support MIPS and AArch64 landed.
 140
 141 - October 2015: Succeeded to self-host the ELF port. We have noticed
 142   that the linker was faster than the GNU linkers, but we weren't sure
 143   at the time if we would be able to keep the gap as we would add more
 144   features to the linker.
 145
 146 - July 2016: Started working on improving the linker script support.
 147
 148 - December 2016: Succeeded to build the entire FreeBSD base system
 149   including the kernel. We had widen the performance gap against the
 150   GNU linkers.
 151
 152 Internals
 153 ---------
 154
 155 For the internals of the linker, please read :doc:`NewLLD`. It is a bit
 156 outdated but the fundamental concepts remain valid. We'll update the
 157 document soon.
 158
 159 .. toctree::
 160    :maxdepth: 1
 161
 162    NewLLD
 163    WebAssembly
 164    windows_support
 165    missingkeyfunction
 166    error_handling_script
 167    Partitions
 168    ReleaseNotes
 169    ELF/linker_script
 170    ELF/start-stop-gc
 171    ELF/warn_backrefs
 172    MachO/index