Introduction¶

Building with link time optimization requires cooperation fromthe system linker. LTO support on Linux systems is available via thegold linker which supports LTO via plugins. This is the same mechanismused by theGCC LTO project.

The LLVM gold plugin implements the gold plugin interface on top oflibLTO. The same plugin can also be used by other tools such asar andnm. Note that ld.bfd from binutils version 2.21.51.0.2and above also supports LTO via plugins. However, usage of the LLVMgold plugin with ld.bfd is not tested and therefore not officiallysupported or recommended.

As of LLVM 15, the gold plugin will ignore bitcode from the.llvmbcsection inside of ELF object files. However, LTO with bitcode filesis still supported.

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 defaulton your system, run/usr/bin/ld-v. It will report “GNUgold” 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 bybacking up your existing/usr/bin/ld and creating a symbolic linkwithln-s/usr/bin/ld.gold/usr/bin/ld. Alternatively, you can buildwith clang’s-fuse-ld=gold or add-fuse-ld=gold to LDFLAGS, which willcause 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” thenyou 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 pluginsupport.

• Download, configure and build gold with plugin support:

  $gitclone--depth1git://sourceware.org/git/binutils-gdb.gitbinutils$mkdirbuild$cdbuild$../binutils/configure--enable-gold--enable-plugins--disable-werror$makeall-gold

  That should leave you withbuild/gold/ld-new which supportsthe-plugin option. Runningmake will additionally buildbuild/binutils/ar andnm-new binaries supporting plugins.

  Once you’re ready to switch to using gold, backup your existing/usr/bin/ld then replace it withld-new. Alternatively, installin/usr/bin/ld.gold and use-fuse-ld=gold as described earlier.

  Optionally, add--enable-gold=default to the above configure invocationto automatically install the newly built gold as the default linker withmakeinstall.

• Build the LLVMgold plugin. Run CMake with-DLLVM_BINUTILS_INCDIR=/path/to/binutils/include. The correct includepath will contain the fileplugin-api.h.

Usage¶

You should produce bitcode files fromclang with the option-flto. This flag will also causeclang to look for the gold plugin inthelib directory under its prefix and pass the-plugin option told. 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 inyour path.

ar andnm also accept the-plugin option and it’s possible toto installLLVMgold.so to/usr/lib/bfd-plugins for a seamless setup.If you built your own gold, be sure to install thear andnm-new youbuilt to/usr/bin.

---a.c---#include<stdio.h>externvoidfoo1(void);externvoidfoo4(void);voidfoo2(void){printf("Foo2\n");}voidfoo3(void){foo4();}intmain(void){foo1();}---b.c---#include<stdio.h>externvoidfoo2(void);voidfoo1(void){foo2();}voidfoo4(void){printf("Foo4");}

---commandlines---$clang-fltoa.c-c-oa.o# <-- a.o is LLVM bitcode file$arqa.aa.o# <-- a.a is an archive with LLVM bitcode$clangb.c-c-ob.o# <-- b.o is native object file$clang-fltoa.ab.o-omain# <-- link with LLVMgold plugin

Quickstart for using LTO with autotooled projects¶

Once your systemld,ar, andnm all support LLVM bitcode,everything is in place for an easy to use LTO build of autotooled projects:

• Follow the instructionson how to build LLVMgold.so.

• Install the newly built binutils to$PREFIX

• CopyRelease/lib/LLVMgold.so to$PREFIX/lib/bfd-plugins/

• Set environment variables ($PREFIX is where you installed clang andbinutils):

  exportCC="$PREFIX/bin/clang -flto"exportCXX="$PREFIX/bin/clang++ -flto"exportAR="$PREFIX/bin/ar"exportNM="$PREFIX/bin/nm"exportRANLIB=/bin/true#ranlib is not needed, and doesn't support .bc files in .a

• Or you can just set your path:

  exportPATH="$PREFIX/bin:$PATH"exportCC="clang -flto"exportCXX="clang++ -flto"exportRANLIB=/bin/true

• Configure and build the project as usual:

  %./configure&&make&&makecheck

The environment variable settings may work for non-autotooled projects too,but you may need to set theLD environment variable as well.

Licensing¶

Gold is licensed under the GPLv3. LLVMgold uses the interface fileplugin-api.h from gold which means that the resultingLLVMgold.sobinary is also GPLv3. This can still be used to link non-GPLv3 programsjust as much as gold could without the plugin.