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