blob: 17bbeb8ba9f85d4bafa35e6f351568d10b548f78 [file] [log] [blame]
Sean Silva34c6b7e2012-10-04 03:56:23 +00001====================
2The LLVM gold plugin
3====================
4
Sean Silva34c6b7e2012-10-04 03:56:23 +00005Introduction
6============
7
8Building with link time optimization requires cooperation from
9the system linker. LTO support on Linux systems requires that you use the
10`gold linker`_ which supports LTO via plugins. This is the same mechanism
11used by the `GCC LTO`_ project.
12
13The LLVM gold plugin implements the gold plugin interface on top of
14:ref:`libLTO`. The same plugin can also be used by other tools such as
15``ar`` and ``nm``.
16
17.. _`gold linker`: http://sourceware.org/binutils
18.. _`GCC LTO`: http://gcc.gnu.org/wiki/LinkTimeOptimization
19.. _`gold plugin interface`: http://gcc.gnu.org/wiki/whopr/driver
20
21.. _lto-how-to-build:
22
23How to build it
24===============
25
26You need to have gold with plugin support and build the LLVMgold plugin.
27Check whether you have gold running ``/usr/bin/ld -v``. It will report "GNU
28gold" or else "GNU ld" if not. If you have gold, check for plugin support
29by running ``/usr/bin/ld -plugin``. If it complains "missing argument" then
30you have plugin support. If not, such as an "unknown option" error then you
31will either need to build gold or install a version with plugin support.
32
33* To build gold with plugin support:
34
35 .. code-block:: bash
36
37 $ mkdir binutils
38 $ cd binutils
39 $ cvs -z 9 -d :pserver:anoncvs@sourceware.org:/cvs/src login
40 {enter "anoncvs" as the password}
41 $ cvs -z 9 -d :pserver:anoncvs@sourceware.org:/cvs/src co binutils
42 $ mkdir build
43 $ cd build
44 $ ../src/configure --enable-gold --enable-plugins
45 $ make all-gold
46
47 That should leave you with ``binutils/build/gold/ld-new`` which supports
48 the ``-plugin`` option. It also built would have
49 ``binutils/build/binutils/ar`` and ``nm-new`` which support plugins but
50 don't have a visible -plugin option, instead relying on the gold plugin
51 being present in ``../lib/bfd-plugins`` relative to where the binaries
52 are placed.
53
54* Build the LLVMgold plugin: Configure LLVM with
55 ``--with-binutils-include=/path/to/binutils/src/include`` and run
56 ``make``.
57
58Usage
59=====
60
61The linker takes a ``-plugin`` option that points to the path of
62the plugin ``.so`` file. To find out what link command ``gcc``
63would run in a given situation, run ``gcc -v [...]`` and
64look for the line where it runs ``collect2``. Replace that with
65``ld-new -plugin /path/to/LLVMgold.so`` to test it out. Once you're
66ready to switch to using gold, backup your existing ``/usr/bin/ld``
67then replace it with ``ld-new``.
68
69You can produce bitcode files from ``clang`` using ``-emit-llvm`` or
70``-flto``, or the ``-O4`` flag which is synonymous with ``-O3 -flto``.
71
72Any of these flags will also cause ``clang`` to look for the gold plugin in
73the ``lib`` directory under its prefix and pass the ``-plugin`` option to
74``ld``. It will not look for an alternate linker, which is why you need
Dmitri Gribenko038c43b2012-10-05 20:50:05 +000075gold to be the installed system linker in your path.
Sean Silva34c6b7e2012-10-04 03:56:23 +000076
77If you want ``ar`` and ``nm`` to work seamlessly as well, install
78``LLVMgold.so`` to ``/usr/lib/bfd-plugins``. If you built your own gold, be
Dmitri Gribenko038c43b2012-10-05 20:50:05 +000079sure to install the ``ar`` and ``nm-new`` you built to ``/usr/bin``.
Sean Silva34c6b7e2012-10-04 03:56:23 +000080
81
82Example of link time optimization
83---------------------------------
84
85The following example shows a worked example of the gold plugin mixing LLVM
86bitcode and native code.
87
88.. code-block:: c
89
90 --- a.c ---
91 #include <stdio.h>
92
93 extern void foo1(void);
94 extern void foo4(void);
95
96 void foo2(void) {
97 printf("Foo2\n");
98 }
99
100 void foo3(void) {
101 foo4();
102 }
103
104 int main(void) {
105 foo1();
106 }
107
108 --- b.c ---
109 #include <stdio.h>
110
111 extern void foo2(void);
112
113 void foo1(void) {
114 foo2();
115 }
116
117 void foo4(void) {
118 printf("Foo4");
119 }
120
121.. code-block:: bash
122
123 --- command lines ---
124 $ clang -flto a.c -c -o a.o # <-- a.o is LLVM bitcode file
125 $ ar q a.a a.o # <-- a.a is an archive with LLVM bitcode
126 $ clang b.c -c -o b.o # <-- b.o is native object file
127 $ clang -flto a.a b.o -o main # <-- link with LLVMgold plugin
128
129Gold informs the plugin that foo3 is never referenced outside the IR,
130leading LLVM to delete that function. However, unlike in the :ref:`libLTO
131example <libLTO-example>` gold does not currently eliminate foo4.
132
133Quickstart for using LTO with autotooled projects
134=================================================
135
136Once your system ``ld``, ``ar``, and ``nm`` all support LLVM bitcode,
137everything is in place for an easy to use LTO build of autotooled projects:
138
139* Follow the instructions :ref:`on how to build LLVMgold.so
140 <lto-how-to-build>`.
141
142* Install the newly built binutils to ``$PREFIX``
143
144* Copy ``Release/lib/LLVMgold.so`` to ``$PREFIX/lib/bfd-plugins/``
145
146* Set environment variables (``$PREFIX`` is where you installed clang and
147 binutils):
148
149 .. code-block:: bash
150
151 export CC="$PREFIX/bin/clang -flto"
152 export CXX="$PREFIX/bin/clang++ -flto"
153 export AR="$PREFIX/bin/ar"
154 export NM="$PREFIX/bin/nm"
155 export RANLIB=/bin/true #ranlib is not needed, and doesn't support .bc files in .a
156 export CFLAGS="-O4"
157
158* Or you can just set your path:
159
160 .. code-block:: bash
161
162 export PATH="$PREFIX/bin:$PATH"
163 export CC="clang -flto"
164 export CXX="clang++ -flto"
165 export RANLIB=/bin/true
166 export CFLAGS="-O4"
167* Configure and build the project as usual:
168
169 .. code-block:: bash
170
171 % ./configure && make && make check
172
173The environment variable settings may work for non-autotooled projects too,
174but you may need to set the ``LD`` environment variable as well.
175
176Licensing
177=========
178
179Gold is licensed under the GPLv3. LLVMgold uses the interface file
Dmitri Gribenko038c43b2012-10-05 20:50:05 +0000180``plugin-api.h`` from gold which means that the resulting ``LLVMgold.so``
Sean Silva34c6b7e2012-10-04 03:56:23 +0000181binary is also GPLv3. This can still be used to link non-GPLv3 programs
182just as much as gold could without the plugin.