/usr/share/doc/llvm-3.5-doc/html/GoldPlugin.html is in llvm-3.5-doc 1:3.5-4ubuntu2~trusty2.
This file is owned by root:root, with mode 0o644.
The actual contents of the file can be viewed below.
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 | <!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="Content-Type" content="text/html; charset=utf-8" />
<title>The LLVM gold plugin — LLVM 3.5 documentation</title>
<link rel="stylesheet" href="_static/llvm-theme.css" type="text/css" />
<link rel="stylesheet" href="_static/pygments.css" type="text/css" />
<script type="text/javascript">
var DOCUMENTATION_OPTIONS = {
URL_ROOT: './',
VERSION: '3.5',
COLLAPSE_INDEX: false,
FILE_SUFFIX: '.html',
HAS_SOURCE: true
};
</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>
<link rel="top" title="LLVM 3.5 documentation" href="index.html" />
<link rel="next" title="LLVM’s Optional Rich Disassembly Output" href="MarkedUpDisassembly.html" />
<link rel="prev" title="Debugging JIT-ed Code With GDB" href="DebuggingJITedCode.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">
<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="MarkedUpDisassembly.html" title="LLVM’s Optional Rich Disassembly Output"
accesskey="N">next</a> |</li>
<li class="right" >
<a href="DebuggingJITedCode.html" title="Debugging JIT-ed Code With GDB"
accesskey="P">previous</a> |</li>
<li><a href="http://llvm.org/">LLVM Home</a> | </li>
<li><a href="index.html">Documentation</a>»</li>
</ul>
</div>
<div class="document">
<div class="documentwrapper">
<div class="body">
<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 requires that you use 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"><em>libLTO</em></a>. The same plugin can also be used by other tools such as
<tt class="docutils literal"><span class="pre">ar</span></tt> and <tt class="docutils literal"><span class="pre">nm</span></tt>.</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.
Check whether you have gold running <tt class="docutils literal"><span class="pre">/usr/bin/ld</span> <span class="pre">-v</span></tt>. It will report “GNU
gold” or else “GNU ld” if not. If you have gold, check for plugin support
by running <tt class="docutils literal"><span class="pre">/usr/bin/ld</span> <span class="pre">-plugin</span></tt>. If it complains “missing argument” then
you have plugin support. If not, such as an “unknown option” error then you
will either need to build gold or install a version with plugin support.</p>
<ul>
<li><p class="first">Download, configure and build gold with plugin support:</p>
<div class="highlight-bash"><div class="highlight"><pre><span class="nv">$ </span>git clone --depth 1 git://sourceware.org/git/binutils-gdb.git binutils
<span class="nv">$ </span>mkdir build
<span class="nv">$ </span><span class="nb">cd </span>build
<span class="nv">$ </span>../binutils/configure --enable-gold --enable-plugins --disable-werror
<span class="nv">$ </span>make all-gold
</pre></div>
</div>
<p>That should leave you with <tt class="docutils literal"><span class="pre">build/gold/ld-new</span></tt> which supports
the <tt class="docutils literal"><span class="pre">-plugin</span></tt> option. Running <tt class="docutils literal"><span class="pre">make</span></tt> will additionally build
<tt class="docutils literal"><span class="pre">build/binutils/ar</span></tt> and <tt class="docutils literal"><span class="pre">nm-new</span></tt> binaries supporting plugins.</p>
</li>
<li><p class="first">Build the LLVMgold plugin: Configure LLVM with
<tt class="docutils literal"><span class="pre">--with-binutils-include=/path/to/binutils/include</span></tt> and run
<tt class="docutils literal"><span class="pre">make</span></tt>.</p>
</li>
</ul>
</div>
<div class="section" id="usage">
<h2>Usage<a class="headerlink" href="#usage" title="Permalink to this headline">¶</a></h2>
<p>The linker takes a <tt class="docutils literal"><span class="pre">-plugin</span></tt> option that points to the path of
the plugin <tt class="docutils literal"><span class="pre">.so</span></tt> file. To find out what link command <tt class="docutils literal"><span class="pre">gcc</span></tt>
would run in a given situation, run <tt class="docutils literal"><span class="pre">gcc</span> <span class="pre">-v</span> <span class="pre">[...]</span></tt> and
look for the line where it runs <tt class="docutils literal"><span class="pre">collect2</span></tt>. Replace that with
<tt class="docutils literal"><span class="pre">ld-new</span> <span class="pre">-plugin</span> <span class="pre">/path/to/LLVMgold.so</span></tt> to test it out. Once you’re
ready to switch to using gold, backup your existing <tt class="docutils literal"><span class="pre">/usr/bin/ld</span></tt>
then replace it with <tt class="docutils literal"><span class="pre">ld-new</span></tt>.</p>
<p>You should produce bitcode files from <tt class="docutils literal"><span class="pre">clang</span></tt> with the option
<tt class="docutils literal"><span class="pre">-flto</span></tt>. This flag will also cause <tt class="docutils literal"><span class="pre">clang</span></tt> to look for the gold plugin in
the <tt class="docutils literal"><span class="pre">lib</span></tt> directory under its prefix and pass the <tt class="docutils literal"><span class="pre">-plugin</span></tt> option to
<tt class="docutils literal"><span class="pre">ld</span></tt>. It will not look for an alternate linker, which is why you need
gold to be the installed system linker in your path.</p>
<p><tt class="docutils literal"><span class="pre">ar</span></tt> and <tt class="docutils literal"><span class="pre">nm</span></tt> also accept the <tt class="docutils literal"><span class="pre">-plugin</span></tt> option and it’s possible to
to install <tt class="docutils literal"><span class="pre">LLVMgold.so</span></tt> to <tt class="docutils literal"><span class="pre">/usr/lib/bfd-plugins</span></tt> for a seamless setup.
If you built your own gold, be sure to install the <tt class="docutils literal"><span class="pre">ar</span></tt> and <tt class="docutils literal"><span class="pre">nm-new</span></tt> you
built to <tt class="docutils literal"><span class="pre">/usr/bin</span></tt>.</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"><div class="highlight"><pre><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 <stdio.h></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="nf">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 <stdio.h></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"><div class="highlight"><pre>--- <span class="nb">command </span>lines ---
<span class="nv">$ </span>clang -flto a.c -c -o a.o <span class="c"># <-- a.o is LLVM bitcode file</span>
<span class="nv">$ </span>ar q a.a a.o <span class="c"># <-- a.a is an archive with LLVM bitcode</span>
<span class="nv">$ </span>clang b.c -c -o b.o <span class="c"># <-- b.o is native object file</span>
<span class="nv">$ </span>clang -flto a.a b.o -o main <span class="c"># <-- 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"><em>libLTO
example</em></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 <tt class="docutils literal"><span class="pre">ld</span></tt>, <tt class="docutils literal"><span class="pre">ar</span></tt>, and <tt class="docutils literal"><span class="pre">nm</span></tt> all support LLVM bitcode,
everything is in place for an easy to use LTO build of autotooled projects:</p>
<ul>
<li><p class="first">Follow the instructions <a class="reference internal" href="#lto-how-to-build"><em>on how to build LLVMgold.so</em></a>.</p>
</li>
<li><p class="first">Install the newly built binutils to <tt class="docutils literal"><span class="pre">$PREFIX</span></tt></p>
</li>
<li><p class="first">Copy <tt class="docutils literal"><span class="pre">Release/lib/LLVMgold.so</span></tt> to <tt class="docutils literal"><span class="pre">$PREFIX/lib/bfd-plugins/</span></tt></p>
</li>
<li><p class="first">Set environment variables (<tt class="docutils literal"><span class="pre">$PREFIX</span></tt> is where you installed clang and
binutils):</p>
<div class="highlight-bash"><div class="highlight"><pre><span class="nb">export </span><span class="nv">CC</span><span class="o">=</span><span class="s2">"$PREFIX/bin/clang -flto"</span>
<span class="nb">export </span><span class="nv">CXX</span><span class="o">=</span><span class="s2">"$PREFIX/bin/clang++ -flto"</span>
<span class="nb">export </span><span class="nv">AR</span><span class="o">=</span><span class="s2">"$PREFIX/bin/ar"</span>
<span class="nb">export </span><span class="nv">NM</span><span class="o">=</span><span class="s2">"$PREFIX/bin/nm"</span>
<span class="nb">export </span><span class="nv">RANLIB</span><span class="o">=</span>/bin/true <span class="c">#ranlib is not needed, and doesn't support .bc files in .a</span>
</pre></div>
</div>
</li>
<li><p class="first">Or you can just set your path:</p>
<div class="highlight-bash"><div class="highlight"><pre><span class="nb">export </span><span class="nv">PATH</span><span class="o">=</span><span class="s2">"$PREFIX/bin:$PATH"</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 class="first">Configure and build the project as usual:</p>
<div class="highlight-bash"><div class="highlight"><pre>% ./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 <tt class="docutils literal"><span class="pre">LD</span></tt> 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
<tt class="docutils literal"><span class="pre">plugin-api.h</span></tt> from gold which means that the resulting <tt class="docutils literal"><span class="pre">LLVMgold.so</span></tt>
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>
</div>
<div class="clearer"></div>
</div>
<div class="related">
<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="MarkedUpDisassembly.html" title="LLVM’s Optional Rich Disassembly Output"
>next</a> |</li>
<li class="right" >
<a href="DebuggingJITedCode.html" title="Debugging JIT-ed Code With GDB"
>previous</a> |</li>
<li><a href="http://llvm.org/">LLVM Home</a> | </li>
<li><a href="index.html">Documentation</a>»</li>
</ul>
</div>
<div class="footer">
© Copyright 2003-2014, LLVM Project.
Last updated on 2015-02-12.
Created using <a href="http://sphinx-doc.org/">Sphinx</a> 1.2.2.
</div>
</body>
</html>
|