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