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. Run CMake with 48 ``-DLLVM_BINUTILS_INCDIR=/path/to/binutils/include``. The correct include 49 path will contain the file ``plugin-api.h``. 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. 173
