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 is available via 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``. Note that ld.bfd from binutils version 2.21.51.0.2 16and above also supports LTO via plugins. However, usage of the LLVM 17gold plugin with ld.bfd is not tested and therefore not officially 18supported or recommended. 19 20.. _`gold linker`: http://sourceware.org/binutils 21.. _`GCC LTO`: http://gcc.gnu.org/wiki/LinkTimeOptimization 22.. _`gold plugin interface`: http://gcc.gnu.org/wiki/whopr/driver 23 24.. _lto-how-to-build: 25 26How to build it 27=============== 28 29You need to have gold with plugin support and build the LLVMgold plugin. 30The gold linker is installed as ld.gold. To see whether gold is the default 31on your system, run ``/usr/bin/ld -v``. It will report "GNU 32gold" or else "GNU ld" if not. If gold is already installed at 33``/usr/bin/ld.gold``, one option is to simply make that the default by 34backing up your existing ``/usr/bin/ld`` and creating a symbolic link 35with ``ln -s /usr/bin/ld.gold /usr/bin/ld``. Alternatively, you can build 36with clang's ``-fuse-ld=gold`` or add ``-fuse-ld=gold`` to LDFLAGS, which will 37cause the clang driver to invoke ``/usr/bin/ld.gold`` directly. 38 39If you have gold installed, check for plugin support by running 40``/usr/bin/ld.gold -plugin``. If it complains "missing argument" then 41you have plugin support. If not, and you get an error such as "unknown option", 42then you will either need to build gold or install a version with plugin 43support. 44 45* Download, configure and build gold with plugin support: 46 47 .. code-block:: bash 48 49 $ git clone --depth 1 git://sourceware.org/git/binutils-gdb.git binutils 50 $ mkdir build 51 $ cd build 52 $ ../binutils/configure --enable-gold --enable-plugins --disable-werror 53 $ make all-gold 54 55 That should leave you with ``build/gold/ld-new`` which supports 56 the ``-plugin`` option. Running ``make`` will additionally build 57 ``build/binutils/ar`` and ``nm-new`` binaries supporting plugins. 58 59 Once you're ready to switch to using gold, backup your existing 60 ``/usr/bin/ld`` then replace it with ``ld-new``. Alternatively, install 61 in ``/usr/bin/ld.gold`` and use ``-fuse-ld=gold`` as described earlier. 62 63 Optionally, add ``--enable-gold=default`` to the above configure invocation 64 to automatically install the newly built gold as the default linker with 65 ``make install``. 66 67* Build the LLVMgold plugin. Run CMake with 68 ``-DLLVM_BINUTILS_INCDIR=/path/to/binutils/include``. The correct include 69 path will contain the file ``plugin-api.h``. 70 71Usage 72===== 73 74You should produce bitcode files from ``clang`` with the option 75``-flto``. This flag will also cause ``clang`` to look for the gold plugin in 76the ``lib`` directory under its prefix and pass the ``-plugin`` option to 77``ld``. It will not look for an alternate linker without ``-fuse-ld=gold``, 78which is why you otherwise need gold to be the installed system linker in 79your path. 80 81``ar`` and ``nm`` also accept the ``-plugin`` option and it's possible to 82to install ``LLVMgold.so`` to ``/usr/lib/bfd-plugins`` for a seamless setup. 83If you built your own gold, be sure to install the ``ar`` and ``nm-new`` you 84built to ``/usr/bin``. 85 86 87Example of link time optimization 88--------------------------------- 89 90The following example shows a worked example of the gold plugin mixing LLVM 91bitcode and native code. 92 93.. code-block:: c 94 95 --- a.c --- 96 #include <stdio.h> 97 98 extern void foo1(void); 99 extern void foo4(void); 100 101 void foo2(void) { 102 printf("Foo2\n"); 103 } 104 105 void foo3(void) { 106 foo4(); 107 } 108 109 int main(void) { 110 foo1(); 111 } 112 113 --- b.c --- 114 #include <stdio.h> 115 116 extern void foo2(void); 117 118 void foo1(void) { 119 foo2(); 120 } 121 122 void foo4(void) { 123 printf("Foo4"); 124 } 125 126.. code-block:: bash 127 128 --- command lines --- 129 $ clang -flto a.c -c -o a.o # <-- a.o is LLVM bitcode file 130 $ ar q a.a a.o # <-- a.a is an archive with LLVM bitcode 131 $ clang b.c -c -o b.o # <-- b.o is native object file 132 $ clang -flto a.a b.o -o main # <-- link with LLVMgold plugin 133 134Gold informs the plugin that foo3 is never referenced outside the IR, 135leading LLVM to delete that function. However, unlike in the :ref:`libLTO 136example <libLTO-example>` gold does not currently eliminate foo4. 137 138Quickstart for using LTO with autotooled projects 139================================================= 140 141Once your system ``ld``, ``ar``, and ``nm`` all support LLVM bitcode, 142everything is in place for an easy to use LTO build of autotooled projects: 143 144* Follow the instructions :ref:`on how to build LLVMgold.so 145 <lto-how-to-build>`. 146 147* Install the newly built binutils to ``$PREFIX`` 148 149* Copy ``Release/lib/LLVMgold.so`` to ``$PREFIX/lib/bfd-plugins/`` 150 151* Set environment variables (``$PREFIX`` is where you installed clang and 152 binutils): 153 154 .. code-block:: bash 155 156 export CC="$PREFIX/bin/clang -flto" 157 export CXX="$PREFIX/bin/clang++ -flto" 158 export AR="$PREFIX/bin/ar" 159 export NM="$PREFIX/bin/nm" 160 export RANLIB=/bin/true #ranlib is not needed, and doesn't support .bc files in .a 161 162* Or you can just set your path: 163 164 .. code-block:: bash 165 166 export PATH="$PREFIX/bin:$PATH" 167 export CC="clang -flto" 168 export CXX="clang++ -flto" 169 export RANLIB=/bin/true 170* Configure and build the project as usual: 171 172 .. code-block:: bash 173 174 % ./configure && make && make check 175 176The environment variable settings may work for non-autotooled projects too, 177but you may need to set the ``LD`` environment variable as well. 178 179Licensing 180========= 181 182Gold is licensed under the GPLv3. LLVMgold uses the interface file 183``plugin-api.h`` from gold which means that the resulting ``LLVMgold.so`` 184binary is also GPLv3. This can still be used to link non-GPLv3 programs 185just as much as gold could without the plugin. 186