-
Notifications
You must be signed in to change notification settings - Fork 0
/
index.html
331 lines (317 loc) · 16 KB
/
index.html
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
"http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta http-equiv="X-UA-Compatible" content="IE=Edge" />
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
<title>LLD - The LLVM Linker — lld 11 documentation</title>
<link rel="stylesheet" href="_static/llvm.css" type="text/css" />
<link rel="stylesheet" href="_static/pygments.css" type="text/css" />
<script type="text/javascript" id="documentation_options" data-url_root="./" src="_static/documentation_options.js"></script>
<script type="text/javascript" src="_static/jquery.js"></script>
<script type="text/javascript" src="_static/underscore.js"></script>
<script type="text/javascript" src="_static/doctools.js"></script>
<script type="text/javascript" src="_static/language_data.js"></script>
<link rel="shortcut icon" href="_static/favicon.ico"/>
<link rel="index" title="Index" href="genindex.html" />
<link rel="search" title="Search" href="search.html" />
<link rel="next" title="The ELF, COFF and Wasm Linkers" href="NewLLD.html" />
<style type="text/css">
table.right { float: right; margin-left: 20px; }
table.right td { border: 1px solid #ccc; }
</style>
</head><body>
<div class="logo">
<a href="#"><img src="_static/logo.png" alt="LLVM Documentation"/></a>
</div>
<div class="related" role="navigation" aria-label="related navigation">
<h3>Navigation</h3>
<ul>
<li class="right" style="margin-right: 10px">
<a href="genindex.html" title="General Index"
accesskey="I">index</a></li>
<li class="right" >
<a href="NewLLD.html" title="The ELF, COFF and Wasm Linkers"
accesskey="N">next</a> |</li>
<li><a href="#">lld Home</a> | </li>
</ul>
</div>
<div class="sphinxsidebar" role="navigation" aria-label="main navigation">
<div class="sphinxsidebarwrapper">
<h3><a href="#">Table of Contents</a></h3>
<ul>
<li><a class="reference internal" href="#">LLD - The LLVM Linker</a><ul>
<li><a class="reference internal" href="#features">Features</a></li>
<li><a class="reference internal" href="#performance">Performance</a></li>
<li><a class="reference internal" href="#build">Build</a></li>
<li><a class="reference internal" href="#using-lld">Using LLD</a></li>
<li><a class="reference internal" href="#history">History</a></li>
<li><a class="reference internal" href="#internals">Internals</a></li>
</ul>
</li>
</ul>
<h4>Next topic</h4>
<p class="topless"><a href="NewLLD.html"
title="next chapter">The ELF, COFF and Wasm Linkers</a></p>
<div role="note" aria-label="source link">
<h3>This Page</h3>
<ul class="this-page-menu">
<li><a href="_sources/index.rst.txt"
rel="nofollow">Show Source</a></li>
</ul>
</div><h3>Bugs</h3>
<p>lld bugs should be reported at the
LLVM <a href="https://bugs.llvm.org/">Bugzilla</a>.</p>
<div id="searchbox" style="display: none" role="search">
<h3>Quick search</h3>
<div class="searchformwrapper">
<form class="search" action="search.html" method="get">
<input type="text" name="q" />
<input type="submit" value="Go" />
<input type="hidden" name="check_keywords" value="yes" />
<input type="hidden" name="area" value="default" />
</form>
</div>
</div>
<script type="text/javascript">$('#searchbox').show(0);</script>
</div>
</div>
<div class="document">
<div class="documentwrapper">
<div class="bodywrapper">
<div class="body" role="main">
<div class="section" id="lld-the-llvm-linker">
<h1>LLD - The LLVM Linker<a class="headerlink" href="#lld-the-llvm-linker" title="Permalink to this headline">¶</a></h1>
<p>LLD is a linker from the LLVM project that is a drop-in replacement
for system linkers and runs much faster than them. It also provides
features that are useful for toolchain developers.</p>
<p>The linker supports ELF (Unix), PE/COFF (Windows), Mach-O (macOS) and
WebAssembly in descending order of completeness. Internally, LLD consists of
several different linkers. The ELF port is the one that will be described in
this document. The PE/COFF port is complete, including
Windows debug info (PDB) support. The WebAssembly port is still a work in
progress (See <a class="reference internal" href="WebAssembly.html"><span class="doc">WebAssembly lld port</span></a>). The Mach-O port is built based on a
different architecture than the others. For the details about Mach-O, please
read <a class="reference internal" href="AtomLLD.html"><span class="doc">ATOM-based lld</span></a>.</p>
<div class="section" id="features">
<h2>Features<a class="headerlink" href="#features" title="Permalink to this headline">¶</a></h2>
<ul>
<li><p class="first">LLD is a drop-in replacement for the GNU linkers that accepts the
same command line arguments and linker scripts as GNU.</p>
<p>We are currently working closely with the FreeBSD project to make
LLD default system linker in future versions of the operating
system, so we are serious about addressing compatibility issues. As
of February 2017, LLD is able to link the entire FreeBSD/amd64 base
system including the kernel. With a few work-in-progress patches it
can link approximately 95% of the ports collection on AMD64. For the
details, see <a class="reference external" href="https://www.freebsd.org/news/status/report-2016-10-2016-12.html#Using-LLVM%27s-LLD-Linker-as-FreeBSD%27s-System-Linker">FreeBSD quarterly status report</a>.</p>
</li>
<li><p class="first">LLD is very fast. When you link a large program on a multicore
machine, you can expect that LLD runs more than twice as fast as the GNU
gold linker. Your mileage may vary, though.</p>
</li>
<li><p class="first">It supports various CPUs/ABIs including x86-64, x86, x32, AArch64,
ARM, MIPS 32/64 big/little-endian, PowerPC, PowerPC 64 and AMDGPU.
Among these, x86-64, AArch64, and ARM (>= v6) are production quality.
MIPS seems decent too. x86 should be OK but is not well tested yet.</p>
</li>
<li><p class="first">It is always a cross-linker, meaning that it always supports all the
above targets however it was built. In fact, we don’t provide a
build-time option to enable/disable each target. This should make it
easy to use our linker as part of a cross-compile toolchain.</p>
</li>
<li><p class="first">You can embed LLD in your program to eliminate dependencies on
external linkers. All you have to do is to construct object files
and command line arguments just like you would do to invoke an
external linker and then call the linker’s main function,
<code class="docutils literal notranslate"><span class="pre">lld::elf::link</span></code>, from your code.</p>
</li>
<li><p class="first">It is small. We are using LLVM libObject library to read from object
files, so it is not a completely fair comparison, but as of February
2017, LLD/ELF consists only of 21k lines of C++ code while GNU gold
consists of 198k lines of C++ code.</p>
</li>
<li><p class="first">Link-time optimization (LTO) is supported by default. Essentially,
all you have to do to do LTO is to pass the <code class="docutils literal notranslate"><span class="pre">-flto</span></code> option to clang.
Then clang creates object files not in the native object file format
but in LLVM bitcode format. LLD reads bitcode object files, compile
them using LLVM and emit an output file. Because in this way LLD can
see the entire program, it can do the whole program optimization.</p>
</li>
<li><p class="first">Some very old features for ancient Unix systems (pre-90s or even
before that) have been removed. Some default settings have been
tuned for the 21st century. For example, the stack is marked as
non-executable by default to tighten security.</p>
</li>
</ul>
</div>
<div class="section" id="performance">
<h2>Performance<a class="headerlink" href="#performance" title="Permalink to this headline">¶</a></h2>
<p>This is a link time comparison on a 2-socket 20-core 40-thread Xeon
E5-2680 2.80 GHz machine with an SSD drive. We ran gold and lld with
or without multi-threading support. To disable multi-threading, we
added <code class="docutils literal notranslate"><span class="pre">-no-threads</span></code> to the command lines.</p>
<table border="1" class="docutils">
<colgroup>
<col width="12%" />
<col width="11%" />
<col width="12%" />
<col width="20%" />
<col width="18%" />
<col width="15%" />
<col width="13%" />
</colgroup>
<tbody valign="top">
<tr class="row-odd"><td>Program</td>
<td>Output size</td>
<td>GNU ld</td>
<td>GNU gold w/o threads</td>
<td>GNU gold w/threads</td>
<td>lld w/o threads</td>
<td>lld w/threads</td>
</tr>
<tr class="row-even"><td>ffmpeg dbg</td>
<td>92 MiB</td>
<td>1.72s</td>
<td>1.16s</td>
<td>1.01s</td>
<td>0.60s</td>
<td>0.35s</td>
</tr>
<tr class="row-odd"><td>mysqld dbg</td>
<td>154 MiB</td>
<td>8.50s</td>
<td>2.96s</td>
<td>2.68s</td>
<td>1.06s</td>
<td>0.68s</td>
</tr>
<tr class="row-even"><td>clang dbg</td>
<td>1.67 GiB</td>
<td>104.03s</td>
<td>34.18s</td>
<td>23.49s</td>
<td>14.82s</td>
<td>5.28s</td>
</tr>
<tr class="row-odd"><td>chromium dbg</td>
<td>1.14 GiB</td>
<td>209.05s <a class="footnote-reference" href="#id2" id="id1">[1]</a></td>
<td>64.70s</td>
<td>60.82s</td>
<td>27.60s</td>
<td>16.70s</td>
</tr>
</tbody>
</table>
<p>As you can see, lld is significantly faster than GNU linkers.
Note that this is just a benchmark result of our environment.
Depending on number of available cores, available amount of memory or
disk latency/throughput, your results may vary.</p>
<table class="docutils footnote" frame="void" id="id2" rules="none">
<colgroup><col class="label" /><col /></colgroup>
<tbody valign="top">
<tr><td class="label"><a class="fn-backref" href="#id1">[1]</a></td><td>Since GNU ld doesn’t support the <code class="docutils literal notranslate"><span class="pre">-icf=all</span></code> and
<code class="docutils literal notranslate"><span class="pre">-gdb-index</span></code> options, we removed them from the command line
for GNU ld. GNU ld would have been slower than this if it had
these options.</td></tr>
</tbody>
</table>
</div>
<div class="section" id="build">
<h2>Build<a class="headerlink" href="#build" title="Permalink to this headline">¶</a></h2>
<p>If you have already checked out LLVM using SVN, you can check out LLD
under <code class="docutils literal notranslate"><span class="pre">tools</span></code> directory just like you probably did for clang. For the
details, see <a class="reference external" href="http://llvm.org/docs/GettingStarted.html">Getting Started with the LLVM System</a>.</p>
<p>If you haven’t checked out LLVM, the easiest way to build LLD is to
check out the entire LLVM projects/sub-projects from a git mirror and
build that tree. You need <cite>cmake</cite> and of course a C++ compiler.</p>
<div class="highlight-console notranslate"><div class="highlight"><pre><span></span><span class="gp">$</span> git clone https://github.com/llvm/llvm-project llvm-project
<span class="gp">$</span> mkdir build
<span class="gp">$</span> <span class="nb">cd</span> build
<span class="gp">$</span> cmake -DCMAKE_BUILD_TYPE<span class="o">=</span>Release -DLLVM_ENABLE_PROJECTS<span class="o">=</span>lld -DCMAKE_INSTALL_PREFIX<span class="o">=</span>/usr/local ../llvm-project/llvm
<span class="gp">$</span> make install
</pre></div>
</div>
</div>
<div class="section" id="using-lld">
<h2>Using LLD<a class="headerlink" href="#using-lld" title="Permalink to this headline">¶</a></h2>
<p>LLD is installed as <code class="docutils literal notranslate"><span class="pre">ld.lld</span></code>. On Unix, linkers are invoked by
compiler drivers, so you are not expected to use that command
directly. There are a few ways to tell compiler drivers to use ld.lld
instead of the default linker.</p>
<p>The easiest way to do that is to overwrite the default linker. After
installing LLD to somewhere on your disk, you can create a symbolic
link by doing <code class="docutils literal notranslate"><span class="pre">ln</span> <span class="pre">-s</span> <span class="pre">/path/to/ld.lld</span> <span class="pre">/usr/bin/ld</span></code> so that
<code class="docutils literal notranslate"><span class="pre">/usr/bin/ld</span></code> is resolved to LLD.</p>
<p>If you don’t want to change the system setting, you can use clang’s
<code class="docutils literal notranslate"><span class="pre">-fuse-ld</span></code> option. In this way, you want to set <code class="docutils literal notranslate"><span class="pre">-fuse-ld=lld</span></code> to
LDFLAGS when building your programs.</p>
<p>LLD leaves its name and version number to a <code class="docutils literal notranslate"><span class="pre">.comment</span></code> section in an
output. If you are in doubt whether you are successfully using LLD or
not, run <code class="docutils literal notranslate"><span class="pre">readelf</span> <span class="pre">--string-dump</span> <span class="pre">.comment</span> <span class="pre"><output-file></span></code> and examine the
output. If the string “Linker: LLD” is included in the output, you are
using LLD.</p>
</div>
<div class="section" id="history">
<h2>History<a class="headerlink" href="#history" title="Permalink to this headline">¶</a></h2>
<p>Here is a brief project history of the ELF and COFF ports.</p>
<ul class="simple">
<li>May 2015: We decided to rewrite the COFF linker and did that.
Noticed that the new linker is much faster than the MSVC linker.</li>
<li>July 2015: The new ELF port was developed based on the COFF linker
architecture.</li>
<li>September 2015: The first patches to support MIPS and AArch64 landed.</li>
<li>October 2015: Succeeded to self-host the ELF port. We have noticed
that the linker was faster than the GNU linkers, but we weren’t sure
at the time if we would be able to keep the gap as we would add more
features to the linker.</li>
<li>July 2016: Started working on improving the linker script support.</li>
<li>December 2016: Succeeded to build the entire FreeBSD base system
including the kernel. We had widen the performance gap against the
GNU linkers.</li>
</ul>
</div>
<div class="section" id="internals">
<h2>Internals<a class="headerlink" href="#internals" title="Permalink to this headline">¶</a></h2>
<p>For the internals of the linker, please read <a class="reference internal" href="NewLLD.html"><span class="doc">The ELF, COFF and Wasm Linkers</span></a>. It is a bit
outdated but the fundamental concepts remain valid. We’ll update the
document soon.</p>
<div class="toctree-wrapper compound">
<ul>
<li class="toctree-l1"><a class="reference internal" href="NewLLD.html">The ELF, COFF and Wasm Linkers</a></li>
<li class="toctree-l1"><a class="reference internal" href="NewLLD.html#design">Design</a></li>
<li class="toctree-l1"><a class="reference internal" href="AtomLLD.html">ATOM-based lld</a></li>
<li class="toctree-l1"><a class="reference internal" href="WebAssembly.html">WebAssembly lld port</a></li>
<li class="toctree-l1"><a class="reference internal" href="windows_support.html">Windows support</a></li>
<li class="toctree-l1"><a class="reference internal" href="missingkeyfunction.html">Missing Key Function</a></li>
<li class="toctree-l1"><a class="reference internal" href="Partitions.html">Partitions</a></li>
<li class="toctree-l1"><a class="reference internal" href="ReleaseNotes.html">lld 11.0.0 Release Notes</a></li>
</ul>
</div>
</div>
</div>
</div>
</div>
</div>
<div class="clearer"></div>
</div>
<div class="related" role="navigation" aria-label="related navigation">
<h3>Navigation</h3>
<ul>
<li class="right" style="margin-right: 10px">
<a href="genindex.html" title="General Index"
>index</a></li>
<li class="right" >
<a href="NewLLD.html" title="The ELF, COFF and Wasm Linkers"
>next</a> |</li>
<li><a href="#">lld Home</a> | </li>
</ul>
</div>
<div class="footer" role="contentinfo">
© Copyright 2011-2020, LLVM Project.
Last updated on 2020-02-14.
Created using <a href="http://sphinx-doc.org/">Sphinx</a> 1.8.5.
</div>
</body>
</html>