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