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