1====================
2The LLVM gold plugin
3====================
4
5Introduction
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 should produce bitcode files from ``clang`` with the option
70``-flto``. This flag will also cause ``clang`` to look for the gold plugin in
71the ``lib`` directory under its prefix and pass the ``-plugin`` option to
72``ld``. It will not look for an alternate linker, which is why you need
73gold to be the installed system linker in your path.
74
75If you want ``ar`` and ``nm`` to work seamlessly as well, install
76``LLVMgold.so`` to ``/usr/lib/bfd-plugins``. If you built your own gold, be
77sure to install the ``ar`` and ``nm-new`` you built to ``/usr/bin``.
78
79
80Example of link time optimization
81---------------------------------
82
83The following example shows a worked example of the gold plugin mixing LLVM
84bitcode and native code.
85
86.. code-block:: c
87
88   --- a.c ---
89   #include <stdio.h>
90
91   extern void foo1(void);
92   extern void foo4(void);
93
94   void foo2(void) {
95     printf("Foo2\n");
96   }
97
98   void foo3(void) {
99     foo4();
100   }
101
102   int main(void) {
103     foo1();
104   }
105
106   --- b.c ---
107   #include <stdio.h>
108
109   extern void foo2(void);
110
111   void foo1(void) {
112     foo2();
113   }
114
115   void foo4(void) {
116     printf("Foo4");
117   }
118
119.. code-block:: bash
120
121   --- command lines ---
122   $ clang -flto a.c -c -o a.o      # <-- a.o is LLVM bitcode file
123   $ ar q a.a a.o                   # <-- a.a is an archive with LLVM bitcode
124   $ clang b.c -c -o b.o            # <-- b.o is native object file
125   $ clang -flto a.a b.o -o main    # <-- link with LLVMgold plugin
126
127Gold informs the plugin that foo3 is never referenced outside the IR,
128leading LLVM to delete that function. However, unlike in the :ref:`libLTO
129example <libLTO-example>` gold does not currently eliminate foo4.
130
131Quickstart for using LTO with autotooled projects
132=================================================
133
134Once your system ``ld``, ``ar``, and ``nm`` all support LLVM bitcode,
135everything is in place for an easy to use LTO build of autotooled projects:
136
137* Follow the instructions :ref:`on how to build LLVMgold.so
138  <lto-how-to-build>`.
139
140* Install the newly built binutils to ``$PREFIX``
141
142* Copy ``Release/lib/LLVMgold.so`` to ``$PREFIX/lib/bfd-plugins/``
143
144* Set environment variables (``$PREFIX`` is where you installed clang and
145  binutils):
146
147  .. code-block:: bash
148
149     export CC="$PREFIX/bin/clang -flto"
150     export CXX="$PREFIX/bin/clang++ -flto"
151     export AR="$PREFIX/bin/ar"
152     export NM="$PREFIX/bin/nm"
153     export RANLIB=/bin/true #ranlib is not needed, and doesn't support .bc files in .a
154
155* Or you can just set your path:
156
157  .. code-block:: bash
158
159     export PATH="$PREFIX/bin:$PATH"
160     export CC="clang -flto"
161     export CXX="clang++ -flto"
162     export RANLIB=/bin/true
163* Configure and build the project as usual:
164
165  .. code-block:: bash
166
167     % ./configure && make && make check
168
169The environment variable settings may work for non-autotooled projects too,
170but you may need to set the ``LD`` environment variable as well.
171
172Licensing
173=========
174
175Gold is licensed under the GPLv3. LLVMgold uses the interface file
176``plugin-api.h`` from gold which means that the resulting ``LLVMgold.so``
177binary is also GPLv3. This can still be used to link non-GPLv3 programs
178just as much as gold could without the plugin.
179