]>
Commit | Line | Data |
---|---|---|
970d7e83 LB |
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 | ||
1a4d82fc | 33 | * Download, configure and build gold with plugin support: |
970d7e83 LB |
34 | |
35 | .. code-block:: bash | |
36 | ||
1a4d82fc | 37 | $ git clone --depth 1 git://sourceware.org/git/binutils-gdb.git binutils |
970d7e83 LB |
38 | $ mkdir build |
39 | $ cd build | |
1a4d82fc | 40 | $ ../binutils/configure --enable-gold --enable-plugins --disable-werror |
970d7e83 LB |
41 | $ make all-gold |
42 | ||
1a4d82fc JJ |
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. | |
970d7e83 | 46 | |
85aaf69f SL |
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``. | |
970d7e83 LB |
52 | |
53 | Usage | |
54 | ===== | |
55 | ||
56 | The linker takes a ``-plugin`` option that points to the path of | |
57 | the plugin ``.so`` file. To find out what link command ``gcc`` | |
58 | would run in a given situation, run ``gcc -v [...]`` and | |
59 | look 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 | |
61 | ready to switch to using gold, backup your existing ``/usr/bin/ld`` | |
62 | then replace it with ``ld-new``. | |
63 | ||
1a4d82fc JJ |
64 | You should produce bitcode files from ``clang`` with the option |
65 | ``-flto``. This flag will also cause ``clang`` to look for the gold plugin in | |
970d7e83 LB |
66 | the ``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 | |
68 | gold to be the installed system linker in your path. | |
69 | ||
1a4d82fc JJ |
70 | ``ar`` and ``nm`` also accept the ``-plugin`` option and it's possible to |
71 | to install ``LLVMgold.so`` to ``/usr/lib/bfd-plugins`` for a seamless setup. | |
72 | If you built your own gold, be sure to install the ``ar`` and ``nm-new`` you | |
73 | built to ``/usr/bin``. | |
970d7e83 LB |
74 | |
75 | ||
76 | Example of link time optimization | |
77 | --------------------------------- | |
78 | ||
79 | The following example shows a worked example of the gold plugin mixing LLVM | |
80 | bitcode 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 | ||
123 | Gold informs the plugin that foo3 is never referenced outside the IR, | |
124 | leading LLVM to delete that function. However, unlike in the :ref:`libLTO | |
125 | example <libLTO-example>` gold does not currently eliminate foo4. | |
126 | ||
127 | Quickstart for using LTO with autotooled projects | |
128 | ================================================= | |
129 | ||
130 | Once your system ``ld``, ``ar``, and ``nm`` all support LLVM bitcode, | |
131 | everything 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 | |
970d7e83 LB |
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 | |
970d7e83 LB |
159 | * Configure and build the project as usual: |
160 | ||
161 | .. code-block:: bash | |
162 | ||
163 | % ./configure && make && make check | |
164 | ||
165 | The environment variable settings may work for non-autotooled projects too, | |
166 | but you may need to set the ``LD`` environment variable as well. | |
167 | ||
168 | Licensing | |
169 | ========= | |
170 | ||
171 | Gold is licensed under the GPLv3. LLVMgold uses the interface file | |
172 | ``plugin-api.h`` from gold which means that the resulting ``LLVMgold.so`` | |
173 | binary is also GPLv3. This can still be used to link non-GPLv3 programs | |
174 | just as much as gold could without the plugin. |