docs/GoldPlugin.rst

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