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
|
<!DOCTYPE html>
<html>
<head>
<meta charset="utf-8" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
<title>The LLVM gold plugin — LLVM 13 documentation</title>
<link rel="stylesheet" href="_static/pygments.css" type="text/css" />
<link rel="stylesheet" href="_static/llvm-theme.css" type="text/css" />
<script id="documentation_options" data-url_root="./" src="_static/documentation_options.js"></script>
<script src="_static/jquery.js"></script>
<script src="_static/underscore.js"></script>
<script src="_static/doctools.js"></script>
<link rel="index" title="Index" href="genindex.html" />
<link rel="search" title="Search" href="search.html" />
<link rel="next" title="How To Build On ARM" href="HowToBuildOnARM.html" />
<link rel="prev" title="Extending LLVM: Adding instructions, intrinsics, types, etc." href="ExtendingLLVM.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="index.html">
<img src="_static/logo.png"
alt="LLVM Logo" width="250" height="88"/></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="HowToBuildOnARM.html" title="How To Build On ARM"
accesskey="N">next</a> |</li>
<li class="right" >
<a href="ExtendingLLVM.html" title="Extending LLVM: Adding instructions, intrinsics, types, etc."
accesskey="P">previous</a> |</li>
<li><a href="https://llvm.org/">LLVM Home</a> | </li>
<li><a href="index.html">Documentation</a>»</li>
<li class="nav-item nav-item-1"><a href="UserGuides.html" accesskey="U">User Guides</a> »</li>
<li class="nav-item nav-item-this"><a href="">The LLVM gold plugin</a></li>
</ul>
</div>
<div class="sphinxsidebar" role="navigation" aria-label="main navigation">
<div class="sphinxsidebarwrapper">
<h3>Documentation</h3>
<ul class="want-points">
<li><a href="https://llvm.org/docs/GettingStartedTutorials.html">Getting Started/Tutorials</a></li>
<li><a href="https://llvm.org/docs/UserGuides.html">User Guides</a></li>
<li><a href="https://llvm.org/docs/Reference.html">Reference</a></li>
</ul>
<h3>Getting Involved</h3>
<ul class="want-points">
<li><a href="https://llvm.org/docs/Contributing.html">Contributing to LLVM</a></li>
<li><a href="https://llvm.org/docs/HowToSubmitABug.html">Submitting Bug Reports</a></li>
<li><a href="https://llvm.org/docs/GettingInvolved.html#mailing-lists">Mailing Lists</a></li>
<li><a href="https://llvm.org/docs/GettingInvolved.html#irc">IRC</a></li>
<li><a href="https://llvm.org/docs/GettingInvolved.html#meetups-and-social-events">Meetups and Social Events</a></li>
</ul>
<h3>Additional Links</h3>
<ul class="want-points">
<li><a href="https://llvm.org/docs/FAQ.html">FAQ</a></li>
<li><a href="https://llvm.org/docs/Lexicon.html">Glossary</a></li>
<li><a href="https://llvm.org/pubs">Publications</a></li>
<li><a href="https://github.com/llvm/llvm-project//">Github Repository</a></li>
</ul>
<div role="note" aria-label="source link">
<h3>This Page</h3>
<ul class="this-page-menu">
<li><a href="_sources/GoldPlugin.rst.txt"
rel="nofollow">Show Source</a></li>
</ul>
</div>
<div id="searchbox" style="display: none" role="search">
<h3 id="searchlabel">Quick search</h3>
<div class="searchformwrapper">
<form class="search" action="search.html" method="get">
<input type="text" name="q" aria-labelledby="searchlabel" />
<input type="submit" value="Go" />
</form>
</div>
</div>
<script>$('#searchbox').show(0);</script>
</div>
</div>
<div class="document">
<div class="documentwrapper">
<div class="bodywrapper">
<div class="body" role="main">
<div class="section" id="the-llvm-gold-plugin">
<h1>The LLVM gold plugin<a class="headerlink" href="#the-llvm-gold-plugin" title="Permalink to this headline">¶</a></h1>
<div class="section" id="introduction">
<h2>Introduction<a class="headerlink" href="#introduction" title="Permalink to this headline">¶</a></h2>
<p>Building with link time optimization requires cooperation from
the system linker. LTO support on Linux systems is available via the
<a class="reference external" href="http://sourceware.org/binutils">gold linker</a> which supports LTO via plugins. This is the same mechanism
used by the <a class="reference external" href="http://gcc.gnu.org/wiki/LinkTimeOptimization">GCC LTO</a> project.</p>
<p>The LLVM gold plugin implements the gold plugin interface on top of
<a class="reference internal" href="LinkTimeOptimization.html#liblto"><span class="std std-ref">libLTO</span></a>. The same plugin can also be used by other tools such as
<code class="docutils literal notranslate"><span class="pre">ar</span></code> and <code class="docutils literal notranslate"><span class="pre">nm</span></code>. Note that ld.bfd from binutils version 2.21.51.0.2
and above also supports LTO via plugins. However, usage of the LLVM
gold plugin with ld.bfd is not tested and therefore not officially
supported or recommended.</p>
</div>
<div class="section" id="how-to-build-it">
<span id="lto-how-to-build"></span><h2>How to build it<a class="headerlink" href="#how-to-build-it" title="Permalink to this headline">¶</a></h2>
<p>You need to have gold with plugin support and build the LLVMgold plugin.
The gold linker is installed as ld.gold. To see whether gold is the default
on your system, run <code class="docutils literal notranslate"><span class="pre">/usr/bin/ld</span> <span class="pre">-v</span></code>. It will report “GNU
gold” or else “GNU ld” if not. If gold is already installed at
<code class="docutils literal notranslate"><span class="pre">/usr/bin/ld.gold</span></code>, one option is to simply make that the default by
backing up your existing <code class="docutils literal notranslate"><span class="pre">/usr/bin/ld</span></code> and creating a symbolic link
with <code class="docutils literal notranslate"><span class="pre">ln</span> <span class="pre">-s</span> <span class="pre">/usr/bin/ld.gold</span> <span class="pre">/usr/bin/ld</span></code>. Alternatively, you can build
with clang’s <code class="docutils literal notranslate"><span class="pre">-fuse-ld=gold</span></code> or add <code class="docutils literal notranslate"><span class="pre">-fuse-ld=gold</span></code> to LDFLAGS, which will
cause the clang driver to invoke <code class="docutils literal notranslate"><span class="pre">/usr/bin/ld.gold</span></code> directly.</p>
<p>If you have gold installed, check for plugin support by running
<code class="docutils literal notranslate"><span class="pre">/usr/bin/ld.gold</span> <span class="pre">-plugin</span></code>. If it complains “missing argument” then
you have plugin support. If not, and you get an error such as “unknown option”,
then you will either need to build gold or install a version with plugin
support.</p>
<ul>
<li><p>Download, configure and build gold with plugin support:</p>
<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span>$ git clone --depth <span class="m">1</span> git://sourceware.org/git/binutils-gdb.git binutils
$ mkdir build
$ <span class="nb">cd</span> build
$ ../binutils/configure --enable-gold --enable-plugins --disable-werror
$ make all-gold
</pre></div>
</div>
<p>That should leave you with <code class="docutils literal notranslate"><span class="pre">build/gold/ld-new</span></code> which supports
the <code class="docutils literal notranslate"><span class="pre">-plugin</span></code> option. Running <code class="docutils literal notranslate"><span class="pre">make</span></code> will additionally build
<code class="docutils literal notranslate"><span class="pre">build/binutils/ar</span></code> and <code class="docutils literal notranslate"><span class="pre">nm-new</span></code> binaries supporting plugins.</p>
<p>Once you’re ready to switch to using gold, backup your existing
<code class="docutils literal notranslate"><span class="pre">/usr/bin/ld</span></code> then replace it with <code class="docutils literal notranslate"><span class="pre">ld-new</span></code>. Alternatively, install
in <code class="docutils literal notranslate"><span class="pre">/usr/bin/ld.gold</span></code> and use <code class="docutils literal notranslate"><span class="pre">-fuse-ld=gold</span></code> as described earlier.</p>
<p>Optionally, add <code class="docutils literal notranslate"><span class="pre">--enable-gold=default</span></code> to the above configure invocation
to automatically install the newly built gold as the default linker with
<code class="docutils literal notranslate"><span class="pre">make</span> <span class="pre">install</span></code>.</p>
</li>
<li><p>Build the LLVMgold plugin. Run CMake with
<code class="docutils literal notranslate"><span class="pre">-DLLVM_BINUTILS_INCDIR=/path/to/binutils/include</span></code>. The correct include
path will contain the file <code class="docutils literal notranslate"><span class="pre">plugin-api.h</span></code>.</p></li>
</ul>
</div>
<div class="section" id="usage">
<h2>Usage<a class="headerlink" href="#usage" title="Permalink to this headline">¶</a></h2>
<p>You should produce bitcode files from <code class="docutils literal notranslate"><span class="pre">clang</span></code> with the option
<code class="docutils literal notranslate"><span class="pre">-flto</span></code>. This flag will also cause <code class="docutils literal notranslate"><span class="pre">clang</span></code> to look for the gold plugin in
the <code class="docutils literal notranslate"><span class="pre">lib</span></code> directory under its prefix and pass the <code class="docutils literal notranslate"><span class="pre">-plugin</span></code> option to
<code class="docutils literal notranslate"><span class="pre">ld</span></code>. It will not look for an alternate linker without <code class="docutils literal notranslate"><span class="pre">-fuse-ld=gold</span></code>,
which is why you otherwise need gold to be the installed system linker in
your path.</p>
<p><code class="docutils literal notranslate"><span class="pre">ar</span></code> and <code class="docutils literal notranslate"><span class="pre">nm</span></code> also accept the <code class="docutils literal notranslate"><span class="pre">-plugin</span></code> option and it’s possible to
to install <code class="docutils literal notranslate"><span class="pre">LLVMgold.so</span></code> to <code class="docutils literal notranslate"><span class="pre">/usr/lib/bfd-plugins</span></code> for a seamless setup.
If you built your own gold, be sure to install the <code class="docutils literal notranslate"><span class="pre">ar</span></code> and <code class="docutils literal notranslate"><span class="pre">nm-new</span></code> you
built to <code class="docutils literal notranslate"><span class="pre">/usr/bin</span></code>.</p>
<div class="section" id="example-of-link-time-optimization">
<h3>Example of link time optimization<a class="headerlink" href="#example-of-link-time-optimization" title="Permalink to this headline">¶</a></h3>
<p>The following example shows a worked example of the gold plugin mixing LLVM
bitcode and native code.</p>
<div class="highlight-c notranslate"><div class="highlight"><pre><span></span><span class="o">---</span> <span class="n">a</span><span class="p">.</span><span class="n">c</span> <span class="o">---</span>
<span class="cp">#include</span> <span class="cpf"><stdio.h></span><span class="cp"></span>
<span class="k">extern</span> <span class="kt">void</span> <span class="n">foo1</span><span class="p">(</span><span class="kt">void</span><span class="p">);</span>
<span class="k">extern</span> <span class="kt">void</span> <span class="n">foo4</span><span class="p">(</span><span class="kt">void</span><span class="p">);</span>
<span class="kt">void</span> <span class="nf">foo2</span><span class="p">(</span><span class="kt">void</span><span class="p">)</span> <span class="p">{</span>
<span class="n">printf</span><span class="p">(</span><span class="s">"Foo2</span><span class="se">\n</span><span class="s">"</span><span class="p">);</span>
<span class="p">}</span>
<span class="kt">void</span> <span class="nf">foo3</span><span class="p">(</span><span class="kt">void</span><span class="p">)</span> <span class="p">{</span>
<span class="n">foo4</span><span class="p">();</span>
<span class="p">}</span>
<span class="kt">int</span> <span class="nf">main</span><span class="p">(</span><span class="kt">void</span><span class="p">)</span> <span class="p">{</span>
<span class="n">foo1</span><span class="p">();</span>
<span class="p">}</span>
<span class="o">---</span> <span class="n">b</span><span class="p">.</span><span class="n">c</span> <span class="o">---</span>
<span class="cp">#include</span> <span class="cpf"><stdio.h></span><span class="cp"></span>
<span class="k">extern</span> <span class="kt">void</span> <span class="n">foo2</span><span class="p">(</span><span class="kt">void</span><span class="p">);</span>
<span class="kt">void</span> <span class="nf">foo1</span><span class="p">(</span><span class="kt">void</span><span class="p">)</span> <span class="p">{</span>
<span class="n">foo2</span><span class="p">();</span>
<span class="p">}</span>
<span class="kt">void</span> <span class="nf">foo4</span><span class="p">(</span><span class="kt">void</span><span class="p">)</span> <span class="p">{</span>
<span class="n">printf</span><span class="p">(</span><span class="s">"Foo4"</span><span class="p">);</span>
<span class="p">}</span>
</pre></div>
</div>
<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span>--- <span class="nb">command</span> lines ---
$ clang -flto a.c -c -o a.o <span class="c1"># <-- a.o is LLVM bitcode file</span>
$ ar q a.a a.o <span class="c1"># <-- a.a is an archive with LLVM bitcode</span>
$ clang b.c -c -o b.o <span class="c1"># <-- b.o is native object file</span>
$ clang -flto a.a b.o -o main <span class="c1"># <-- link with LLVMgold plugin</span>
</pre></div>
</div>
<p>Gold informs the plugin that foo3 is never referenced outside the IR,
leading LLVM to delete that function. However, unlike in the <a class="reference internal" href="LinkTimeOptimization.html#liblto-example"><span class="std std-ref">libLTO
example</span></a> gold does not currently eliminate foo4.</p>
</div>
</div>
<div class="section" id="quickstart-for-using-lto-with-autotooled-projects">
<h2>Quickstart for using LTO with autotooled projects<a class="headerlink" href="#quickstart-for-using-lto-with-autotooled-projects" title="Permalink to this headline">¶</a></h2>
<p>Once your system <code class="docutils literal notranslate"><span class="pre">ld</span></code>, <code class="docutils literal notranslate"><span class="pre">ar</span></code>, and <code class="docutils literal notranslate"><span class="pre">nm</span></code> all support LLVM bitcode,
everything is in place for an easy to use LTO build of autotooled projects:</p>
<ul>
<li><p>Follow the instructions <a class="reference internal" href="#lto-how-to-build"><span class="std std-ref">on how to build LLVMgold.so</span></a>.</p></li>
<li><p>Install the newly built binutils to <code class="docutils literal notranslate"><span class="pre">$PREFIX</span></code></p></li>
<li><p>Copy <code class="docutils literal notranslate"><span class="pre">Release/lib/LLVMgold.so</span></code> to <code class="docutils literal notranslate"><span class="pre">$PREFIX/lib/bfd-plugins/</span></code></p></li>
<li><p>Set environment variables (<code class="docutils literal notranslate"><span class="pre">$PREFIX</span></code> is where you installed clang and
binutils):</p>
<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span><span class="nb">export</span> <span class="nv">CC</span><span class="o">=</span><span class="s2">"</span><span class="nv">$PREFIX</span><span class="s2">/bin/clang -flto"</span>
<span class="nb">export</span> <span class="nv">CXX</span><span class="o">=</span><span class="s2">"</span><span class="nv">$PREFIX</span><span class="s2">/bin/clang++ -flto"</span>
<span class="nb">export</span> <span class="nv">AR</span><span class="o">=</span><span class="s2">"</span><span class="nv">$PREFIX</span><span class="s2">/bin/ar"</span>
<span class="nb">export</span> <span class="nv">NM</span><span class="o">=</span><span class="s2">"</span><span class="nv">$PREFIX</span><span class="s2">/bin/nm"</span>
<span class="nb">export</span> <span class="nv">RANLIB</span><span class="o">=</span>/bin/true <span class="c1">#ranlib is not needed, and doesn't support .bc files in .a</span>
</pre></div>
</div>
</li>
<li><p>Or you can just set your path:</p>
<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span><span class="nb">export</span> <span class="nv">PATH</span><span class="o">=</span><span class="s2">"</span><span class="nv">$PREFIX</span><span class="s2">/bin:</span><span class="nv">$PATH</span><span class="s2">"</span>
<span class="nb">export</span> <span class="nv">CC</span><span class="o">=</span><span class="s2">"clang -flto"</span>
<span class="nb">export</span> <span class="nv">CXX</span><span class="o">=</span><span class="s2">"clang++ -flto"</span>
<span class="nb">export</span> <span class="nv">RANLIB</span><span class="o">=</span>/bin/true
</pre></div>
</div>
</li>
<li><p>Configure and build the project as usual:</p>
<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span>% ./configure <span class="o">&&</span> make <span class="o">&&</span> make check
</pre></div>
</div>
</li>
</ul>
<p>The environment variable settings may work for non-autotooled projects too,
but you may need to set the <code class="docutils literal notranslate"><span class="pre">LD</span></code> environment variable as well.</p>
</div>
<div class="section" id="licensing">
<h2>Licensing<a class="headerlink" href="#licensing" title="Permalink to this headline">¶</a></h2>
<p>Gold is licensed under the GPLv3. LLVMgold uses the interface file
<code class="docutils literal notranslate"><span class="pre">plugin-api.h</span></code> from gold which means that the resulting <code class="docutils literal notranslate"><span class="pre">LLVMgold.so</span></code>
binary is also GPLv3. This can still be used to link non-GPLv3 programs
just as much as gold could without the plugin.</p>
</div>
</div>
<div class="clearer"></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="HowToBuildOnARM.html" title="How To Build On ARM"
>next</a> |</li>
<li class="right" >
<a href="ExtendingLLVM.html" title="Extending LLVM: Adding instructions, intrinsics, types, etc."
>previous</a> |</li>
<li><a href="https://llvm.org/">LLVM Home</a> | </li>
<li><a href="index.html">Documentation</a>»</li>
<li class="nav-item nav-item-1"><a href="UserGuides.html" >User Guides</a> »</li>
<li class="nav-item nav-item-this"><a href="">The LLVM gold plugin</a></li>
</ul>
</div>
<div class="footer" role="contentinfo">
© Copyright 2003-2021, LLVM Project.
Last updated on 2021-09-18.
Created using <a href="https://www.sphinx-doc.org/">Sphinx</a> 3.5.4.
</div>
</body>
</html>
|
