docs/GoldPlugin.rst

   1 .. _gold-plugin:
   2
   3 ====================
   4 The LLVM gold plugin
   5 ====================
   6
   7 .. sectionauthor:: Nick Lewycky
   8
   9 Introduction
  10 ============
  11
  12 Building with link time optimization requires cooperation from
  13 the system linker. LTO support on Linux systems requires that you use the
  14 `gold linker`_ which supports LTO via plugins. This is the same mechanism
  15 used by the `GCC LTO`_ project.
  16
  17 The LLVM gold plugin implements the gold plugin interface on top of
  18 :ref:`libLTO`.  The same plugin can also be used by other tools such as
  19 ``ar`` and ``nm``.
  20
  21 .. _`gold linker`: http://sourceware.org/binutils
  22 .. _`GCC LTO`: http://gcc.gnu.org/wiki/LinkTimeOptimization
  23 .. _`gold plugin interface`: http://gcc.gnu.org/wiki/whopr/driver
  24
  25 .. _lto-how-to-build:
  26
  27 How to build it
  28 ===============
  29
  30 You need to have gold with plugin support and build the LLVMgold plugin.
  31 Check whether you have gold running ``/usr/bin/ld -v``. It will report "GNU
  32 gold" or else "GNU ld" if not. If you have gold, check for plugin support
  33 by running ``/usr/bin/ld -plugin``. If it complains "missing argument" then
  34 you have plugin support. If not, such as an "unknown option" error then you
  35 will either need to build gold or install a version with plugin support.
  36
  37 * To build gold with plugin support:
  38
  39   .. code-block:: bash
  40
  41      $ mkdir binutils
  42      $ cd binutils
  43      $ cvs -z 9 -d :pserver:anoncvs@sourceware.org:/cvs/src login
  44      {enter "anoncvs" as the password}
  45      $ cvs -z 9 -d :pserver:anoncvs@sourceware.org:/cvs/src co binutils
  46      $ mkdir build
  47      $ cd build
  48      $ ../src/configure --enable-gold --enable-plugins
  49      $ make all-gold
  50
  51   That should leave you with ``binutils/build/gold/ld-new`` which supports
  52   the ``-plugin`` option. It also built would have
  53   ``binutils/build/binutils/ar`` and ``nm-new`` which support plugins but
  54   don't have a visible -plugin option, instead relying on the gold plugin
  55   being present in ``../lib/bfd-plugins`` relative to where the binaries
  56   are placed.
  57
  58 * Build the LLVMgold plugin: Configure LLVM with
  59   ``--with-binutils-include=/path/to/binutils/src/include`` and run
  60   ``make``.
  61
  62 Usage
  63 =====
  64
  65 The linker takes a ``-plugin`` option that points to the path of
  66 the plugin ``.so`` file. To find out what link command ``gcc``
  67 would run in a given situation, run ``gcc -v [...]`` and
  68 look for the line where it runs ``collect2``. Replace that with
  69 ``ld-new -plugin /path/to/LLVMgold.so`` to test it out. Once you're
  70 ready to switch to using gold, backup your existing ``/usr/bin/ld``
  71 then replace it with ``ld-new``.
  72
  73 You can produce bitcode files from ``clang`` using ``-emit-llvm`` or
  74 ``-flto``, or the ``-O4`` flag which is synonymous with ``-O3 -flto``.
  75
  76 Any of these flags will also cause ``clang`` to look for the gold plugin in
  77 the ``lib`` directory under its prefix and pass the ``-plugin`` option to
  78 ``ld``. It will not look for an alternate linker, which is why you need
  79 gold to be the installed system linker in your path.
  80
  81 If you want ``ar`` and ``nm`` to work seamlessly as well, install
  82 ``LLVMgold.so`` to ``/usr/lib/bfd-plugins``. If you built your own gold, be
  83 sure to install the ``ar`` and ``nm-new`` you built to ``/usr/bin``.
  84
  85
  86 Example of link time optimization
  87 ---------------------------------
  88
  89 The following example shows a worked example of the gold plugin mixing LLVM
  90 bitcode and native code.
  91
  92 .. code-block:: c
  93
  94    --- a.c ---
  95    #include <stdio.h>
  96
  97    extern void foo1(void);
  98    extern void foo4(void);
  99
 100    void foo2(void) {
 101      printf("Foo2\n");
 102    }
 103
 104    void foo3(void) {
 105      foo4();
 106    }
 107
 108    int main(void) {
 109      foo1();
 110    }
 111
 112    --- b.c ---
 113    #include <stdio.h>
 114
 115    extern void foo2(void);
 116
 117    void foo1(void) {
 118      foo2();
 119    }
 120
 121    void foo4(void) {
 122      printf("Foo4");
 123    }
 124
 125 .. code-block:: bash
 126
 127    --- command lines ---
 128    $ clang -flto a.c -c -o a.o      # <-- a.o is LLVM bitcode file
 129    $ ar q a.a a.o                   # <-- a.a is an archive with LLVM bitcode
 130    $ clang b.c -c -o b.o            # <-- b.o is native object file
 131    $ clang -flto a.a b.o -o main    # <-- link with LLVMgold plugin
 132
 133 Gold informs the plugin that foo3 is never referenced outside the IR,
 134 leading LLVM to delete that function. However, unlike in the :ref:`libLTO
 135 example <libLTO-example>` gold does not currently eliminate foo4.
 136
 137 Quickstart for using LTO with autotooled projects
 138 =================================================
 139
 140 Once your system ``ld``, ``ar``, and ``nm`` all support LLVM bitcode,
 141 everything is in place for an easy to use LTO build of autotooled projects:
 142
 143 * Follow the instructions :ref:`on how to build LLVMgold.so
 144   <lto-how-to-build>`.
 145
 146 * Install the newly built binutils to ``$PREFIX``
 147
 148 * Copy ``Release/lib/LLVMgold.so`` to ``$PREFIX/lib/bfd-plugins/``
 149
 150 * Set environment variables (``$PREFIX`` is where you installed clang and
 151   binutils):
 152
 153   .. code-block:: bash
 154
 155      export CC="$PREFIX/bin/clang -flto"
 156      export CXX="$PREFIX/bin/clang++ -flto"
 157      export AR="$PREFIX/bin/ar"
 158      export NM="$PREFIX/bin/nm"
 159      export RANLIB=/bin/true #ranlib is not needed, and doesn't support .bc files in .a
 160      export CFLAGS="-O4"
 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      export CFLAGS="-O4"
 171 * Configure and build the project as usual:
 172
 173   .. code-block:: bash
 174
 175      % ./configure && make && make check
 176
 177 The environment variable settings may work for non-autotooled projects too,
 178 but you may need to set the ``LD`` environment variable as well.
 179
 180 Licensing
 181 =========
 182
 183 Gold is licensed under the GPLv3. LLVMgold uses the interface file
 184 ``plugin-api.h`` from gold which means that the resulting ``LLVMgold.so``
 185 binary is also GPLv3. This can still be used to link non-GPLv3 programs
 186 just as much as gold could without the plugin.