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