|
150
|
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
|
|
207
|
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.
|
|
150
|
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
|
|
173
|
101 <https://llvm.org/docs/GettingStarted.html>`_.
|
|
150
|
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
|
|
207
|
177 error_handling_script
|
|
150
|
178 Partitions
|
|
|
179 ReleaseNotes
|
|
173
|
180 ELF/linker_script
|
|
207
|
181 ELF/warn_backrefs
|
