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. 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``. 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 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 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 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``. 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 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 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. 175
