X-Git-Url: http://demsky.eecs.uci.edu/git/?a=blobdiff_plain;ds=sidebyside;f=docs%2FGoldPlugin.html;h=68c5cf19280288ced2c771185e39105d4ae58069;hb=a75ce9f5d2236d93c117e861e60e6f3f748c9555;hp=76e49f040d6fd773be12846ab0f136bf0475453a;hpb=fd97aa2bd20c5bda54526c3c075d9b80d1bec52e;p=oota-llvm.git diff --git a/docs/GoldPlugin.html b/docs/GoldPlugin.html index 76e49f040d6..68c5cf19280 100644 --- a/docs/GoldPlugin.html +++ b/docs/GoldPlugin.html @@ -11,7 +11,11 @@
@@ -20,15 +24,15 @@Building with link time optimization requires cooperation with the +
Building with link time optimization requires cooperation from the system linker. LTO support on Linux systems requires that you use -gold which supports for -LTO via plugins. This is the same system used by the upcoming +the gold linker which supports +LTO via plugins. This is the same mechanism used by the GCC LTO -support.
-The LLVMgold plugin implements the gold -plugin interface on -top of +project.
+The LLVM gold plugin implements the +gold plugin interface +on top of libLTO. The same plugin can also be used by other tools such as ar and nm. @@ -37,25 +41,32 @@ The same plugin can also be used by other tools such as ar and
You need to build gold with plugin support and build the LLVMgold -plugin.
+You need to have gold with plugin support and build the LLVMgold +plugin. Check whether you have gold running /usr/bin/ld -v. It will +report “GNU gold” or else “GNU ld” if not. If you have +gold, check for plugin support by running /usr/bin/ld -plugin. If it +complains “missing argument” then you have plugin support. If not, +such as an “unknown option” error then you will either need to +build gold or install a version with plugin support.
mkdir binutils cd binutils cvs -z 9 -d :pserver:anoncvs@sourceware.org:/cvs/src login {enter "anoncvs" as the password} -cvs -z 9 -d :pserver:anoncvs@sourceware.org:/cvs/src co src +cvs -z 9 -d :pserver:anoncvs@sourceware.org:/cvs/src co binutils mkdir build cd build ../src/configure --enable-gold --enable-plugins make all-gold- That should leave you with binutils/build/gold/ld-new which supports the --plugin option. - -
You can produce bitcode files from llvm-gcc using - -emit-llvm or -flto or -O4 which is equivalent - to -O3 -flto.
+ -emit-llvm or -flto, or the -O4 flag which is + synonymous with -O3 -flto.llvm-gcc has a -use-gold-plugin option which looks - for the gold plugin in the same directories as it looks for cc1. - It will not look for an alternate linker, which is why you need gold to be - the installed system linker in your path.
+ for the gold plugin in the same directories as it looks for cc1 and + passes the -plugin option to ld. It will not look for an alternate + linker, which is why you need gold to be the installed system linker in your + path. +If you want ar and nm to work seamlessly as well, install + LLVMgold.so to /usr/lib/bfd-plugins. If you built your + own gold, be sure to install the ar and nm-new you built to + /usr/bin. +
+
The following example shows a worked example of the gold plugin mixing + LLVM bitcode and native code. +
+--- a.c --- +#include <stdio.h> + +extern void foo1(void); +extern void foo4(void); + +void foo2(void) { + printf("Foo2\n"); +} + +void foo3(void) { + foo4(); +} + +int main(void) { + foo1(); +} + +--- b.c --- +#include <stdio.h> + +extern void foo2(void); + +void foo1(void) { + foo2(); +} + +void foo4(void) { + printf("Foo4"); +} + +--- command lines --- +$ llvm-gcc -flto a.c -c -o a.o # <-- a.o is LLVM bitcode file +$ ar q a.a a.o # <-- a.a is an archive with LLVM bitcode +$ llvm-gcc b.c -c -o b.o # <-- b.o is native object file +$ llvm-gcc -use-gold-plugin a.a b.o -o main # <-- link with LLVMgold plugin ++
Gold informs the plugin that foo3 is never referenced outside the IR, + leading LLVM to delete that function. However, unlike in the + libLTO + example gold does not currently eliminate foo4.
Once your system ld, ar and nm all support LLVM + bitcode, everything is in place for an easy to use LTO build of autotooled + projects:
++export CC="$PREFIX/bin/llvm-gcc -use-gold-plugin" +export CXX="$PREFIX/bin/llvm-g++ -use-gold-plugin" +export AR="$PREFIX/bin/ar" +export NM="$PREFIX/bin/nm" +export RANLIB=/bin/true #ranlib is not needed, and doesn't support .bc files in .a +export CFLAGS="-O4" ++
+export PATH="$PREFIX/bin:$PATH" +export CC="llvm-gcc -use-gold-plugin" +export CXX="llvm-g++ -use-gold-plugin" +export RANLIB=/bin/true +export CFLAGS="-O4" ++
The environment variable settings may work for non-autotooled projects + too, but you may need to set the LD environment variable as well.
+Gold is licensed under the GPLv3. LLVMgold uses the interface file plugin-api.h from gold which means that the resulting LLVMgold.so binary is also GPLv3. This can still be used to link non-GPLv3 programs just -as much as gold could without the plugin. +as much as gold could without the plugin.