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* Download, configure and build gold with plugin support:
34
35  .. code-block:: bash
36
37     $ git clone --depth 1 git://sourceware.org/git/binutils-gdb.git binutils
38     $ mkdir build
39     $ cd build
40     $ ../binutils/configure --enable-gold --enable-plugins --disable-werror
41     $ make all-gold
42
43  That should leave you with ``build/gold/ld-new`` which supports
44  the ``-plugin`` option. Running ``make`` will additionally build
45  ``build/binutils/ar`` and ``nm-new`` binaries supporting plugins.
46
47* Build the LLVMgold plugin.  If building with autotools, run configure with
48  ``--with-binutils-include=/path/to/binutils/include`` and run ``make``.
49  If building with CMake, run cmake with
50  ``-DLLVM_BINUTILS_INCDIR=/path/to/binutils/include``.  The correct include
51  path will contain the file ``plugin-api.h``.
52
53Usage
54=====
55
56The linker takes a ``-plugin`` option that points to the path of
57the plugin ``.so`` file. To find out what link command ``gcc``
58would run in a given situation, run ``gcc -v [...]`` and
59look for the line where it runs ``collect2``. Replace that with
60``ld-new -plugin /path/to/LLVMgold.so`` to test it out. Once you're
61ready to switch to using gold, backup your existing ``/usr/bin/ld``
62then replace it with ``ld-new``.
63
64You should produce bitcode files from ``clang`` with the option
65``-flto``. This flag will also cause ``clang`` to look for the gold plugin in
66the ``lib`` directory under its prefix and pass the ``-plugin`` option to
67``ld``. It will not look for an alternate linker, which is why you need
68gold to be the installed system linker in your path.
69
70``ar`` and ``nm`` also accept the ``-plugin`` option and it's possible to
71to install ``LLVMgold.so`` to ``/usr/lib/bfd-plugins`` for a seamless setup.
72If you built your own gold, be sure to install the ``ar`` and ``nm-new`` you
73built to ``/usr/bin``.
74
75
76Example of link time optimization
77---------------------------------
78
79The following example shows a worked example of the gold plugin mixing LLVM
80bitcode and native code.
81
82.. code-block:: c
83
84   --- a.c ---
85   #include <stdio.h>
86
87   extern void foo1(void);
88   extern void foo4(void);
89
90   void foo2(void) {
91     printf("Foo2\n");
92   }
93
94   void foo3(void) {
95     foo4();
96   }
97
98   int main(void) {
99     foo1();
100   }
101
102   --- b.c ---
103   #include <stdio.h>
104
105   extern void foo2(void);
106
107   void foo1(void) {
108     foo2();
109   }
110
111   void foo4(void) {
112     printf("Foo4");
113   }
114
115.. code-block:: bash
116
117   --- command lines ---
118   $ clang -flto a.c -c -o a.o      # <-- a.o is LLVM bitcode file
119   $ ar q a.a a.o                   # <-- a.a is an archive with LLVM bitcode
120   $ clang b.c -c -o b.o            # <-- b.o is native object file
121   $ clang -flto a.a b.o -o main    # <-- link with LLVMgold plugin
122
123Gold informs the plugin that foo3 is never referenced outside the IR,
124leading LLVM to delete that function. However, unlike in the :ref:`libLTO
125example <libLTO-example>` gold does not currently eliminate foo4.
126
127Quickstart for using LTO with autotooled projects
128=================================================
129
130Once your system ``ld``, ``ar``, and ``nm`` all support LLVM bitcode,
131everything is in place for an easy to use LTO build of autotooled projects:
132
133* Follow the instructions :ref:`on how to build LLVMgold.so
134  <lto-how-to-build>`.
135
136* Install the newly built binutils to ``$PREFIX``
137
138* Copy ``Release/lib/LLVMgold.so`` to ``$PREFIX/lib/bfd-plugins/``
139
140* Set environment variables (``$PREFIX`` is where you installed clang and
141  binutils):
142
143  .. code-block:: bash
144
145     export CC="$PREFIX/bin/clang -flto"
146     export CXX="$PREFIX/bin/clang++ -flto"
147     export AR="$PREFIX/bin/ar"
148     export NM="$PREFIX/bin/nm"
149     export RANLIB=/bin/true #ranlib is not needed, and doesn't support .bc files in .a
150
151* Or you can just set your path:
152
153  .. code-block:: bash
154
155     export PATH="$PREFIX/bin:$PATH"
156     export CC="clang -flto"
157     export CXX="clang++ -flto"
158     export RANLIB=/bin/true
159* Configure and build the project as usual:
160
161  .. code-block:: bash
162
163     % ./configure && make && make check
164
165The environment variable settings may work for non-autotooled projects too,
166but you may need to set the ``LD`` environment variable as well.
167
168Licensing
169=========
170
171Gold is licensed under the GPLv3. LLVMgold uses the interface file
172``plugin-api.h`` from gold which means that the resulting ``LLVMgold.so``
173binary is also GPLv3. This can still be used to link non-GPLv3 programs
174just as much as gold could without the plugin.
175