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