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