docs/GoldPlugin.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

<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN"
                      "http://www.w3.org/TR/html4/strict.dtd">
<html>
<head>
  <title>LLVM gold plugin</title>
  <link rel="stylesheet" href="llvm.css" type="text/css">
</head>
<body>
      
<div class="doc_title">LLVM gold plugin</div>
<ol>
  <li><a href="#introduction">Introduction</a></li>
  <li><a href="#build">How to build it</a></li>
  <li><a href="#usage">Usage</a>
  <ul>
    <li><a href="#example1">Example of link time optimization</a></li>
  </ul></li>
  <li><a href="#licensing">Licensing</a></li>
</ol>
<div class="doc_author">Written by Nick Lewycky</div>

<!--=========================================================================-->
<div class="doc_section"><a name="introduction">Introduction</a></div>
<!--=========================================================================-->
<div class="doc_text">
  <p>Building with link time optimization requires cooperation from the
system linker. LTO support on Linux systems requires that you use
the <a href="http://sourceware.org/binutils">gold linker</a> which supports
LTO via plugins. This is the same system used by the upcoming
<a href="http://gcc.gnu.org/wiki/LinkTimeOptimization">GCC LTO</a>
project.</p>
  <p>The LLVM gold plugin implements the
<a href="http://gcc.gnu.org/wiki/whopr/driver">gold plugin interface</a>
on top of
<a href="http://llvm.org/docs/LinkTimeOptimization.html#lto">libLTO</a>.
The same plugin can also be used by other tools such as <tt>ar</tt> and
<tt>nm</tt>.
</div>
<!--=========================================================================-->
<div class="doc_section"><a name="build">How to build it</a></div>
<!--=========================================================================-->
<div class="doc_text">
  <p>You need to build gold with plugin support and build the LLVMgold
plugin.</p>
<ul>
  <li>Build gold with plugin support:
    <pre class="doc_code">
mkdir binutils
cd binutils
cvs -z 9 -d :pserver:anoncvs@sourceware.org:/cvs/src login
<em>{enter "anoncvs" as the password}</em>
cvs -z 9 -d :pserver:anoncvs@sourceware.org:/cvs/src co src
mkdir build
cd build
../src/configure --enable-gold --enable-plugins
make all-gold
</pre>
    That should leave you with binutils/build/gold/ld-new which supports the
<tt>-plugin</tt> option.

    <li>Build the LLVMgold plugin: Configure LLVM with
    <tt>--with-binutils-include=/path/to/binutils/src/include</tt> and run
    <tt>make</tt>.
</ul>
</div>
<!--=========================================================================-->
<div class="doc_section"><a name="usage">Usage</a></div>
<!--=========================================================================-->
<div class="doc_text">
  <p>The linker takes a <tt>-plugin</tt> option that points to the path of
  the plugin <tt>.so</tt> file. To find out what link command <tt>gcc</tt>
  would run in a given situation, run <tt>gcc -v <em>[...]</em></tt> and look
  for the line where it runs <tt>collect2</tt>. Replace that with
  <tt>ld-new -plugin /path/to/LLVMgold.so</tt> to test it out. Once you're
  ready to switch to using gold, backup your existing <tt>/usr/bin/ld</tt>
  then replace it with <tt>ld-new</tt>.</p>
  <p>You can produce bitcode files from <tt>llvm-gcc</tt> using
  <tt>-emit-llvm</tt> or <tt>-flto</tt>, or the <tt>-O4</tt> flag which is
  synonymous with <tt>-O3 -flto</tt>.</p>
  <p><tt>llvm-gcc</tt> has a <tt>-use-gold-plugin</tt> option which looks
  for the gold plugin in the same directories as it looks for <tt>cc1</tt> and
  passes the <tt>-plugin</tt> option to ld. It will not look for an alternate
  linker, which is why you need gold to be the installed system linker in your
  path.</p>
</div>

<!-- ======================================================================= -->
<div class="doc_subsection">
  <a name="example1">Example of link time optimization</a>
</div>

<div class="doc_text">
  <p>The following example shows a worked example of the gold plugin mixing
  LLVM bitcode and native code.
<pre class="doc_code">
--- a.c ---
#include &lt;stdio.h&gt;

extern void foo1(void);
extern void foo4(void);

void foo2(void) {
  printf("Foo2\n");
}

void foo3(void) {
  foo4();
}

int main(void) {
  foo1();
}

--- b.c ---
#include &lt;stdio.h&gt;

extern void foo2(void);

void foo1(void) {
  foo2();
}

void foo4(void) {
  printf("Foo4");
}

--- command lines ---
$ llvm-gcc -flto a.c -c -o a.o              # &lt;-- a.o is LLVM bitcode file
$ llvm-gcc b.c -c -o b.o                    # &lt;-- b.o is native object file
$ llvm-gcc -use-gold-plugin a.o b.o -o main # &lt;-- link with LLVMgold plugin
</pre>
  <p>Gold informs the plugin that foo3 is never referenced outside the IR,
  leading LLVM to delete that function. However, unlike in the
  <a href="http://llvm.org/docs/LinkTimeOptimization.html#example1">libLTO
  example</a> gold does not currently eliminate foo4.</p>
</div>

<!--=========================================================================-->
<div class="doc_section"><a name="licensing">Licensing</a></div>
<!--=========================================================================-->
<div class="doc_text">
Gold is licensed under the GPLv3. LLVMgold uses the interface file
<tt>plugin-api.h</tt> from gold which means that the resulting LLVMgold.so
binary is also GPLv3. This can still be used to link non-GPLv3 programs just
as much as gold could without the plugin.
</div>

<!-- *********************************************************************** -->
<hr>
<address>
  <a href="http://jigsaw.w3.org/css-validator/check/referer"><img
  src="http://jigsaw.w3.org/css-validator/images/vcss-blue" alt="Valid CSS"></a>
  <a href="http://validator.w3.org/check/referer"><img
  src="http://www.w3.org/Icons/valid-html401-blue" alt="Valid HTML 4.01"></a>
  <a href="mailto:nicholas@metrix.on.ca">Nick Lewycky</a><br>
  <a href="http://llvm.org">The LLVM Compiler Infrastructure</a><br>
  Last modified: $Date: 2009-01-01 23:10:51 -0800 (Thu, 01 Jan 2009) $
</address>
</body>
</html>