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