| ==================== |
| The LLVM gold plugin |
| ==================== |
| |
| Introduction |
| ============ |
| |
| Building with link time optimization requires cooperation from |
| the system linker. LTO support on Linux systems is available via the |
| `gold linker`_ which supports LTO via plugins. This is the same mechanism |
| used by the `GCC LTO`_ project. |
| |
| The LLVM gold plugin implements the gold plugin interface on top of |
| :ref:`libLTO`. The same plugin can also be used by other tools such as |
| ``ar`` and ``nm``. Note that ld.bfd from binutils version 2.21.51.0.2 |
| and above also supports LTO via plugins. However, usage of the LLVM |
| gold plugin with ld.bfd is not tested and therefore not officially |
| supported or recommended. |
| |
| .. _`gold linker`: http://sourceware.org/binutils |
| .. _`GCC LTO`: http://gcc.gnu.org/wiki/LinkTimeOptimization |
| .. _`gold plugin interface`: http://gcc.gnu.org/wiki/whopr/driver |
| |
| .. _lto-how-to-build: |
| |
| How to build it |
| =============== |
| |
| You need to have gold with plugin support and build the LLVMgold plugin. |
| The gold linker is installed as ld.gold. To see whether gold is the default |
| on your system, run ``/usr/bin/ld -v``. It will report "GNU |
| gold" or else "GNU ld" if not. If gold is already installed at |
| ``/usr/bin/ld.gold``, one option is to simply make that the default by |
| backing up your existing ``/usr/bin/ld`` and creating a symbolic link |
| with ``ln -s /usr/bin/ld.gold /usr/bin/ld``. Alternatively, you can build |
| with clang's ``-fuse-ld=gold`` or add ``-fuse-ld=gold`` to LDFLAGS, which will |
| cause the clang driver to invoke ``/usr/bin/ld.gold`` directly. |
| |
| If you have gold installed, check for plugin support by running |
| ``/usr/bin/ld.gold -plugin``. If it complains "missing argument" then |
| you have plugin support. If not, and you get an error such as "unknown option", |
| then you will either need to build gold or install a version with plugin |
| support. |
| |
| * Download, configure and build gold with plugin support: |
| |
| .. code-block:: bash |
| |
| $ git clone --depth 1 git://sourceware.org/git/binutils-gdb.git binutils |
| $ mkdir build |
| $ cd build |
| $ ../binutils/configure --enable-gold --enable-plugins --disable-werror |
| $ make all-gold |
| |
| That should leave you with ``build/gold/ld-new`` which supports |
| the ``-plugin`` option. Running ``make`` will additionally build |
| ``build/binutils/ar`` and ``nm-new`` binaries supporting plugins. |
| |
| Once you're ready to switch to using gold, backup your existing |
| ``/usr/bin/ld`` then replace it with ``ld-new``. Alternatively, install |
| in ``/usr/bin/ld.gold`` and use ``-fuse-ld=gold`` as described earlier. |
| |
| Optionally, add ``--enable=gold=default`` to the above configure invocation |
| to automatically install the newly built gold as the default linker with |
| ``make install``. |
| |
| * Build the LLVMgold plugin. Run CMake with |
| ``-DLLVM_BINUTILS_INCDIR=/path/to/binutils/include``. The correct include |
| path will contain the file ``plugin-api.h``. |
| |
| Usage |
| ===== |
| |
| You should produce bitcode files from ``clang`` with the option |
| ``-flto``. This flag will also cause ``clang`` to look for the gold plugin in |
| the ``lib`` directory under its prefix and pass the ``-plugin`` option to |
| ``ld``. It will not look for an alternate linker without ``-fuse-ld=gold``, |
| which is why you otherwise need gold to be the installed system linker in |
| your path. |
| |
| ``ar`` and ``nm`` also accept the ``-plugin`` option and it's possible to |
| to install ``LLVMgold.so`` to ``/usr/lib/bfd-plugins`` for a seamless setup. |
| If you built your own gold, be sure to install the ``ar`` and ``nm-new`` you |
| built to ``/usr/bin``. |
| |
| |
| Example of link time optimization |
| --------------------------------- |
| |
| The following example shows a worked example of the gold plugin mixing LLVM |
| bitcode and native code. |
| |
| .. code-block:: c |
| |
| --- a.c --- |
| #include <stdio.h> |
| |
| extern void foo1(void); |
| extern void foo4(void); |
| |
| void foo2(void) { |
| printf("Foo2\n"); |
| } |
| |
| void foo3(void) { |
| foo4(); |
| } |
| |
| int main(void) { |
| foo1(); |
| } |
| |
| --- b.c --- |
| #include <stdio.h> |
| |
| extern void foo2(void); |
| |
| void foo1(void) { |
| foo2(); |
| } |
| |
| void foo4(void) { |
| printf("Foo4"); |
| } |
| |
| .. code-block:: bash |
| |
| --- command lines --- |
| $ clang -flto a.c -c -o a.o # <-- a.o is LLVM bitcode file |
| $ ar q a.a a.o # <-- a.a is an archive with LLVM bitcode |
| $ clang b.c -c -o b.o # <-- b.o is native object file |
| $ clang -flto a.a b.o -o main # <-- link with LLVMgold plugin |
| |
| Gold informs the plugin that foo3 is never referenced outside the IR, |
| leading LLVM to delete that function. However, unlike in the :ref:`libLTO |
| example <libLTO-example>` gold does not currently eliminate foo4. |
| |
| Quickstart for using LTO with autotooled projects |
| ================================================= |
| |
| Once your system ``ld``, ``ar``, and ``nm`` all support LLVM bitcode, |
| everything is in place for an easy to use LTO build of autotooled projects: |
| |
| * Follow the instructions :ref:`on how to build LLVMgold.so |
| <lto-how-to-build>`. |
| |
| * Install the newly built binutils to ``$PREFIX`` |
| |
| * Copy ``Release/lib/LLVMgold.so`` to ``$PREFIX/lib/bfd-plugins/`` |
| |
| * Set environment variables (``$PREFIX`` is where you installed clang and |
| binutils): |
| |
| .. code-block:: bash |
| |
| export CC="$PREFIX/bin/clang -flto" |
| export CXX="$PREFIX/bin/clang++ -flto" |
| export AR="$PREFIX/bin/ar" |
| export NM="$PREFIX/bin/nm" |
| export RANLIB=/bin/true #ranlib is not needed, and doesn't support .bc files in .a |
| |
| * Or you can just set your path: |
| |
| .. code-block:: bash |
| |
| export PATH="$PREFIX/bin:$PATH" |
| export CC="clang -flto" |
| export CXX="clang++ -flto" |
| export RANLIB=/bin/true |
| * Configure and build the project as usual: |
| |
| .. code-block:: bash |
| |
| % ./configure && make && make check |
| |
| The environment variable settings may work for non-autotooled projects too, |
| but you may need to set the ``LD`` environment variable as well. |
| |
| Licensing |
| ========= |
| |
| Gold is licensed under the GPLv3. LLVMgold uses the interface file |
| ``plugin-api.h`` from gold which means that the resulting ``LLVMgold.so`` |
| binary is also GPLv3. This can still be used to link non-GPLv3 programs |
| just as much as gold could without the plugin. |