190 lines · plain
1====================2The LLVM gold plugin3====================4 5Introduction6============7 8Building with link time optimization requires cooperation from9the system linker. LTO support on Linux systems is available via the10`gold linker`_ which supports LTO via plugins. This is the same mechanism11used by the `GCC LTO`_ project.12 13The LLVM gold plugin implements the gold plugin interface on top of14:ref:`libLTO`. The same plugin can also be used by other tools such as15``ar`` and ``nm``. Note that ld.bfd from binutils version 2.21.51.0.216and above also supports LTO via plugins. However, usage of the LLVM17gold plugin with ld.bfd is not tested and therefore not officially18supported 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 files22is still supported.23 24.. _`gold linker`: http://sourceware.org/binutils25.. _`GCC LTO`: http://gcc.gnu.org/wiki/LinkTimeOptimization26.. _`gold plugin interface`: http://gcc.gnu.org/wiki/whopr/driver27 28.. _lto-how-to-build:29 30How to build it31===============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 default35on your system, run ``/usr/bin/ld -v``. It will report "GNU36gold" or else "GNU ld" if not. If gold is already installed at37``/usr/bin/ld.gold``, one option is to simply make that the default by38backing up your existing ``/usr/bin/ld`` and creating a symbolic link39with ``ln -s /usr/bin/ld.gold /usr/bin/ld``. Alternatively, you can build40with clang's ``-fuse-ld=gold`` or add ``-fuse-ld=gold`` to LDFLAGS, which will41cause the clang driver to invoke ``/usr/bin/ld.gold`` directly.42 43If you have gold installed, check for plugin support by running44``/usr/bin/ld.gold -plugin``. If it complains "missing argument" then45you 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 plugin47support.48 49* Download, configure and build gold with plugin support:50 51 .. code-block:: bash52 53 $ git clone --depth 1 git://sourceware.org/git/binutils-gdb.git binutils54 $ mkdir build55 $ cd build56 $ ../binutils/configure --enable-gold --enable-plugins --disable-werror57 $ make all-gold58 59 That should leave you with ``build/gold/ld-new`` which supports60 the ``-plugin`` option. Running ``make`` will additionally build61 ``build/binutils/ar`` and ``nm-new`` binaries supporting plugins.62 63 Once you're ready to switch to using gold, backup your existing64 ``/usr/bin/ld`` then replace it with ``ld-new``. Alternatively, install65 in ``/usr/bin/ld.gold`` and use ``-fuse-ld=gold`` as described earlier.66 67 Optionally, add ``--enable-gold=default`` to the above configure invocation68 to automatically install the newly built gold as the default linker with69 ``make install``.70 71* Build the LLVMgold plugin. Run CMake with72 ``-DLLVM_BINUTILS_INCDIR=/path/to/binutils/include``. The correct include73 path will contain the file ``plugin-api.h``.74 75Usage76=====77 78You should produce bitcode files from ``clang`` with the option79``-flto``. This flag will also cause ``clang`` to look for the gold plugin in80the ``lib`` directory under its prefix and pass the ``-plugin`` option to81``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 in83your path.84 85``ar`` and ``nm`` also accept the ``-plugin`` option and it's possible to86install ``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`` you88built to ``/usr/bin``.89 90 91Example of link time optimization92---------------------------------93 94The following example shows a worked example of the gold plugin mixing LLVM95bitcode and native code.96 97.. code-block:: c98 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:: bash131 132 --- command lines ---133 $ clang -flto a.c -c -o a.o # <-- a.o is LLVM bitcode file134 $ ar q a.a a.o # <-- a.a is an archive with LLVM bitcode135 $ clang b.c -c -o b.o # <-- b.o is native object file136 $ clang -flto a.a b.o -o main # <-- link with LLVMgold plugin137 138Gold informs the plugin that foo3 is never referenced outside the IR,139leading LLVM to delete that function. However, unlike in the :ref:`libLTO140example <libLTO-example>` gold does not currently eliminate foo4.141 142Quickstart for using LTO with autotooled projects143=================================================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.so149 <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 and156 binutils):157 158 .. code-block:: bash159 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 .a165 166* Or you can just set your path:167 168 .. code-block:: bash169 170 export PATH="$PREFIX/bin:$PATH"171 export CC="clang -flto"172 export CXX="clang++ -flto"173 export RANLIB=/bin/true174* Configure and build the project as usual:175 176 .. code-block:: bash177 178 % ./configure && make && make check179 180The environment variable settings may work for non-autotooled projects too,181but you may need to set the ``LD`` environment variable as well.182 183Licensing184=========185 186Gold is licensed under the GPLv3. LLVMgold uses the interface file187``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 programs189just as much as gold could without the plugin.190