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. Run CMake with 48 ``-DLLVM_BINUTILS_INCDIR=/path/to/binutils/include``. The correct include 49 path will contain the file ``plugin-api.h``. 50 51Usage 52===== 53 54The linker takes a ``-plugin`` option that points to the path of 55the plugin ``.so`` file. To find out what link command ``gcc`` 56would run in a given situation, run ``gcc -v [...]`` and 57look 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 59ready to switch to using gold, backup your existing ``/usr/bin/ld`` 60then replace it with ``ld-new``. 61 62You should produce bitcode files from ``clang`` with the option 63``-flto``. This flag will also cause ``clang`` to look for the gold plugin in 64the ``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 66gold to be the installed system linker in your path. 67 68``ar`` and ``nm`` also accept the ``-plugin`` option and it's possible to 69to install ``LLVMgold.so`` to ``/usr/lib/bfd-plugins`` for a seamless setup. 70If you built your own gold, be sure to install the ``ar`` and ``nm-new`` you 71built to ``/usr/bin``. 72 73 74Example of link time optimization 75--------------------------------- 76 77The following example shows a worked example of the gold plugin mixing LLVM 78bitcode 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 121Gold informs the plugin that foo3 is never referenced outside the IR, 122leading LLVM to delete that function. However, unlike in the :ref:`libLTO 123example <libLTO-example>` gold does not currently eliminate foo4. 124 125Quickstart for using LTO with autotooled projects 126================================================= 127 128Once your system ``ld``, ``ar``, and ``nm`` all support LLVM bitcode, 129everything 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 163The environment variable settings may work for non-autotooled projects too, 164but you may need to set the ``LD`` environment variable as well. 165 166Licensing 167========= 168 169Gold is licensed under the GPLv3. LLVMgold uses the interface file 170``plugin-api.h`` from gold which means that the resulting ``LLVMgold.so`` 171binary is also GPLv3. This can still be used to link non-GPLv3 programs 172just as much as gold could without the plugin. 173