Minor cleanup related to my latest scheduler changes.

[oota-llvm.git] / docs / GoldPlugin.html

diff --git a/docs/GoldPlugin.html b/docs/GoldPlugin.html
index 76e49f040d6fd773be12846ab0f136bf0475453a..68c5cf19280288ced2c771185e39105d4ae58069 100644 (file)
--- a/docs/GoldPlugin.html
+++ b/docs/GoldPlugin.html
@@ -11,7 +11,11 @@
 <ol>
   <li><a href="#introduction">Introduction</a></li>
   <li><a href="#build">How to build it</a></li>
 <ol>
   <li><a href="#introduction">Introduction</a></li>
   <li><a href="#build">How to build it</a></li>

-  <li><a href="#usage">Usage</a></li>
+  <li><a href="#usage">Usage</a>
+  <ul>
+    <li><a href="#example1">Example of link time optimization</a></li>
+    <li><a href="#lto_autotools">Quickstart for using LTO with autotooled projects</a></li>
+  </ul></li>

   <li><a href="#licensing">Licensing</a></li>
 </ol>
 <div class="doc_author">Written by Nick Lewycky</div>
   <li><a href="#licensing">Licensing</a></li>
 </ol>
 <div class="doc_author">Written by Nick Lewycky</div>


@@ -20,15 +24,15 @@
 <div class="doc_section"><a name="introduction">Introduction</a></div>
 <!--=========================================================================-->
 <div class="doc_text">
 <div class="doc_section"><a name="introduction">Introduction</a></div>
 <!--=========================================================================-->
 <div class="doc_text">

-  <p>Building with link time optimization requires cooperation with the
+  <p>Building with link time optimization requires cooperation from the

 system linker. LTO support on Linux systems requires that you use
 system linker. LTO support on Linux systems requires that you use

-<a href="http://sourceware.org/binutils">gold</a> which supports for
-LTO via plugins. This is the same system used by the upcoming
+the <a href="http://sourceware.org/binutils">gold linker</a> which supports
+LTO via plugins. This is the same mechanism used by the

 <a href="http://gcc.gnu.org/wiki/LinkTimeOptimization">GCC LTO</a>
 <a href="http://gcc.gnu.org/wiki/LinkTimeOptimization">GCC LTO</a>

-support.</p>
-  <p>The LLVMgold plugin implements the gold
-<a href="http://gcc.gnu.org/wiki/whopr/driver">plugin interface</a> on
-top of
+project.</p>
+  <p>The LLVM gold plugin implements the
+<a href="http://gcc.gnu.org/wiki/whopr/driver">gold plugin interface</a>
+on top of

 <a href="http://llvm.org/docs/LinkTimeOptimization.html#lto">libLTO</a>.
 The same plugin can also be used by other tools such as <tt>ar</tt> and
 <tt>nm</tt>.
 <a href="http://llvm.org/docs/LinkTimeOptimization.html#lto">libLTO</a>.
 The same plugin can also be used by other tools such as <tt>ar</tt> and
 <tt>nm</tt>.


@@ -37,25 +41,32 @@ The same plugin can also be used by other tools such as <tt>ar</tt> and
 <div class="doc_section"><a name="build">How to build it</a></div>
 <!--=========================================================================-->
 <div class="doc_text">
 <div class="doc_section"><a name="build">How to build it</a></div>
 <!--=========================================================================-->
 <div class="doc_text">

-  <p>You need to build gold with plugin support and build the LLVMgold
-plugin.</p>
+  <p>You need to have gold with plugin support and build the LLVMgold
+plugin. Check whether you have gold running <tt>/usr/bin/ld -v</tt>. It will
+report &#8220;GNU gold&#8221; or else &#8220GNU ld&#8221; if not. If you have
+gold, check for plugin support by running <tt>/usr/bin/ld -plugin</tt>. If it
+complains &#8220missing argument&#8221 then you have plugin support. If not,
+such as an &#8220;unknown option&#8221; error then you will either need to
+build gold or install a version with plugin support.</p>

 <ul>
 <ul>

-  <li>Build gold with plugin support:
+  <li>To build gold with plugin support:

     <pre class="doc_code">
 mkdir binutils
 cd binutils
 cvs -z 9 -d :pserver:anoncvs@sourceware.org:/cvs/src login
 <em>{enter "anoncvs" as the password}</em>
     <pre class="doc_code">
 mkdir binutils
 cd binutils
 cvs -z 9 -d :pserver:anoncvs@sourceware.org:/cvs/src login
 <em>{enter "anoncvs" as the password}</em>

-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
 </pre>
 mkdir build
 cd build
 ../src/configure --enable-gold --enable-plugins
 make all-gold
 </pre>

-    That should leave you with binutils/build/gold/ld-new which supports the
--plugin option.
-
-    <li>Build LLVMgold. Configure LLVM with
+    That should leave you with <tt>binutils/build/gold/ld-new</tt> which supports the <tt>-plugin</tt> option. It also built would have
+<tt>binutils/build/binutils/ar</tt> and <tt>nm-new</tt> which support plugins
+but don't have a visible -plugin option, instead relying on the gold plugin
+being present in <tt>../lib/bfd-plugins</tt> relative to where the binaries are
+placed.
+    <li>Build the LLVMgold plugin: Configure LLVM with

     <tt>--with-binutils-include=/path/to/binutils/src/include</tt> and run
     <tt>make</tt>.
 </ul>
     <tt>--with-binutils-include=/path/to/binutils/src/include</tt> and run
     <tt>make</tt>.
 </ul>


@@ -72,21 +83,119 @@ make all-gold
   ready to switch to using gold, backup your existing <tt>/usr/bin/ld</tt>
   then replace it with <tt>ld-new</tt>.</p>
   <p>You can produce bitcode files from <tt>llvm-gcc</tt> using
   ready to switch to using gold, backup your existing <tt>/usr/bin/ld</tt>
   then replace it with <tt>ld-new</tt>.</p>
   <p>You can produce bitcode files from <tt>llvm-gcc</tt> using

-  <tt>-emit-llvm</tt> or <tt>-flto</tt> or <tt>-O4</tt> which is equivalent
-  to <tt>-O3 -flto</tt>.</p>
+  <tt>-emit-llvm</tt> or <tt>-flto</tt>, or the <tt>-O4</tt> flag which is
+  synonymous with <tt>-O3 -flto</tt>.</p>

   <p><tt>llvm-gcc</tt> has a <tt>-use-gold-plugin</tt> option which looks
   <p><tt>llvm-gcc</tt> has a <tt>-use-gold-plugin</tt> option which looks

-  for the gold plugin in the same directories as it looks for <tt>cc1</tt>.
-  It will not look for an alternate linker, which is why you need gold to be
-  the installed system linker in your path.</p>
+  for the gold plugin in the same directories as it looks for <tt>cc1</tt> and
+  passes the <tt>-plugin</tt> 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.</p>
+  <p>If you want <tt>ar</tt> and <tt>nm</tt> to work seamlessly as well, install
+  <tt>LLVMgold.so</tt> to <tt>/usr/lib/bfd-plugins</tt>. If you built your
+  own gold, be sure to install the <tt>ar</tt> and <tt>nm-new</tt> you built to
+  <tt>/usr/bin</tt>.
+  <p>
+</div>
+
+<!-- ======================================================================= -->
+<div class="doc_subsection">
+  <a name="example1">Example of link time optimization</a>
+</div>
+
+<div class="doc_text">
+  <p>The following example shows a worked example of the gold plugin mixing
+  LLVM bitcode and native code.
+<pre class="doc_code">
+--- a.c ---
+#include &lt;stdio.h&gt;
+
+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 &lt;stdio.h&gt;
+
+extern void foo2(void);
+
+void foo1(void) {
+  foo2();
+}
+
+void foo4(void) {
+  printf("Foo4");
+}
+
+--- command lines ---
+$ llvm-gcc -flto a.c -c -o a.o              # &lt;-- a.o is LLVM bitcode file
+$ ar q a.a a.o                              # &lt;-- a.a is an archive with LLVM bitcode
+$ llvm-gcc b.c -c -o b.o                    # &lt;-- b.o is native object file
+$ llvm-gcc -use-gold-plugin a.a b.o -o main # &lt;-- link with LLVMgold plugin
+</pre>
+  <p>Gold informs the plugin that foo3 is never referenced outside the IR,
+  leading LLVM to delete that function. However, unlike in the
+  <a href="http://llvm.org/docs/LinkTimeOptimization.html#example1">libLTO
+  example</a> gold does not currently eliminate foo4.</p>

 </div>
 </div>

+
+<!--=========================================================================-->
+<div class="doc_section"><a name="lto_autotools">Quickstart for using LTO with autotooled projects</a></div>
+<!--=========================================================================-->
+<div class="doc_text">
+  <p>Once your system <tt>ld</tt>, <tt>ar</tt> and <tt>nm</tt> all support LLVM
+  bitcode, everything is in place for an easy to use LTO build of autotooled
+  projects:</p>
+  <ul>
+    <li>Follow the instructions <a href="#build">on how to build LLVMgold.so</a>.</li>
+    <li>Install the newly built binutils to <tt>$PREFIX</tt></li>
+    <li>Copy <tt>Release/lib/LLVMgold.so</tt> to
+    <tt>$PREFIX/libexec/gcc/x86_64-unknown-linux-gnu/4.2.1/</tt> and
+    <tt>$PREFIX/lib/bfd-plugins/</tt></li>
+    <li>Set environment variables (<tt>$PREFIX</tt> is where you installed llvm-gcc and
+    binutils):
+    <pre class="doc_code">
+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"
+</pre>
+     </li>
+     <li>Or you can just set your path:
+    <pre class="doc_code">
+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"
+</pre>
+     </li>
+     <li>Configure &amp; build the project as usual: <tt>./configure &amp;&amp; make &amp;&amp; make check</tt> </li>
+   </ul>
+   <p> The environment variable settings may work for non-autotooled projects
+   too, but you may need to set the <tt>LD</tt> environment variable as well.</p>
+</div>
+

 <!--=========================================================================-->
 <div class="doc_section"><a name="licensing">Licensing</a></div>
 <!--=========================================================================-->
 <div class="doc_text">
 <!--=========================================================================-->
 <div class="doc_section"><a name="licensing">Licensing</a></div>
 <!--=========================================================================-->
 <div class="doc_text">

-Gold is licensed under the GPLv3. LLVMgold uses the interface file
+  <p>Gold is licensed under the GPLv3. LLVMgold uses the interface file

 <tt>plugin-api.h</tt> from gold which means that the resulting LLVMgold.so
 binary is also GPLv3. This can still be used to link non-GPLv3 programs just
 <tt>plugin-api.h</tt> 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.</p>

 </div>
 
 <!-- *********************************************************************** -->
 </div>
 
 <!-- *********************************************************************** -->


@@ -96,10 +205,9 @@ as much as gold could without the plugin.
   src="http://jigsaw.w3.org/css-validator/images/vcss-blue" alt="Valid CSS"></a>
   <a href="http://validator.w3.org/check/referer"><img
   src="http://www.w3.org/Icons/valid-html401-blue" alt="Valid HTML 4.01"></a>
   src="http://jigsaw.w3.org/css-validator/images/vcss-blue" alt="Valid CSS"></a>
   <a href="http://validator.w3.org/check/referer"><img
   src="http://www.w3.org/Icons/valid-html401-blue" alt="Valid HTML 4.01"></a>

-  Written by the 

   <a href="mailto:nicholas@metrix.on.ca">Nick Lewycky</a><br>
   <a href="http://llvm.org">The LLVM Compiler Infrastructure</a><br>
   <a href="mailto:nicholas@metrix.on.ca">Nick Lewycky</a><br>
   <a href="http://llvm.org">The LLVM Compiler Infrastructure</a><br>

-  Last modified: $Date: 2009-01-01 23:10:51 -0800 (Thu, 01 Jan 2009) $
+  Last modified: $Date: 2010-04-16 23:58:21 -0800 (Fri, 16 Apr 2010) $

 </address>
 </body>
 </html>
 </address>
 </body>
 </html>