maxjhandsome
/
llvm-project
forked from OSchip/llvm-project
1
0
Fork 0
Code Issues Pull Requests Packages Releases Wiki Activity

docs: Sphinxify GoldPlugin document. 

llvm-svn: 165198
This commit is contained in:
Sean Silva 2012-10-04 03:56:23 +00:00
parent 4c8559e0a1
commit fc6de0f2cb
4 changed files with 190 additions and 228 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

227
llvm/docs/GoldPlugin.html
View File

@ -1,227 +0,0 @@
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN"
"http://www.w3.org/TR/html4/strict.dtd">
<html>
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
<title>LLVM gold plugin</title>
<link rel="stylesheet" href="_static/llvm.css" type="text/css">
</head>
<body>
<h1>LLVM gold plugin</h1>
<ol>
<li><a href="#introduction">Introduction</a></li>
<li><a href="#build">How to build it</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>
<!--=========================================================================-->
<h2><a name="introduction">Introduction</a></h2>
<!--=========================================================================-->
<div>
<p>Building with link time optimization requires cooperation from the
system linker. LTO support on Linux systems requires that you use
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>
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="LinkTimeOptimization.html#lto">libLTO</a>.
The same plugin can also be used by other tools such as <tt>ar</tt> and
<tt>nm</tt>.
</div>
<!--=========================================================================-->
<h2><a name="build">How to build it</a></h2>
<!--=========================================================================-->
<div>
<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>
<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>
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>
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>
</div>
<!--=========================================================================-->
<h2><a name="usage">Usage</a></h2>
<!--=========================================================================-->
<div>
<p>The linker takes a <tt>-plugin</tt> option that points to the path of
the plugin <tt>.so</tt> file. To find out what link command <tt>gcc</tt>
would run in a given situation, run <tt>gcc -v <em>[...]</em></tt> and look
for the line where it runs <tt>collect2</tt>. Replace that with
<tt>ld-new -plugin /path/to/LLVMgold.so</tt> to test it out. Once you're
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>clang</tt> using
<tt>-emit-llvm</tt> or <tt>-flto</tt>, or the <tt>-O4</tt> flag which is
synonymous with <tt>-O3 -flto</tt>.</p>
<p>Any of these flags will also cause <tt>clang</tt> to look for the
gold plugin in the <tt>lib</tt> directory under its prefix and pass the
<tt>-plugin</tt> option to <tt>ld</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>
<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>
<!-- ======================================================================= -->
<h3>
<a name="example1">Example of link time optimization</a>
</h3>
<div>
<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 ---
$ clang -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
$ clang b.c -c -o b.o # &lt;-- b.o is native object file
$ clang -flto 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="LinkTimeOptimization.html#example1">libLTO
example</a> gold does not currently eliminate foo4.</p>
</div>
</div>
<!--=========================================================================-->
<h2>
<a name="lto_autotools">
Quickstart for using LTO with autotooled projects
</a>
</h2>
<!--=========================================================================-->
<div>
<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/lib/bfd-plugins/</tt></li>
<li>Set environment variables (<tt>$PREFIX</tt> is where you installed clang and
binutils):
<pre class="doc_code">
export CC="$PREFIX/bin/clang -flto"
export CXX="$PREFIX/bin/clang++ -flto"
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="clang -flto"
export CXX="clang++ -flto"
export RANLIB=/bin/true
export CFLAGS="-O4"
</pre></li>
<li>Configure &amp; build the project as usual:
<pre class="doc_code">
% ./configure &amp;&amp; make &amp;&amp; make check
</pre></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>
<!--=========================================================================-->
<h2><a name="licensing">Licensing</a></h2>
<!--=========================================================================-->
<div>
<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
as much as gold could without the plugin.</p>
</div>
<!-- *********************************************************************** -->
<hr>
<address>
<a href="http://jigsaw.w3.org/css-validator/check/referer"><img
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>
<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: 2010-04-16 23:58:21 -0800 (Fri, 16 Apr 2010) $
</address>
</body>
</html>

186
llvm/docs/GoldPlugin.rst Normal file
View File

@ -0,0 +1,186 @@
.. _gold-plugin:
====================
The LLVM gold plugin
====================
.. sectionauthor:: Nick Lewycky
Introduction
============
Building with link time optimization requires cooperation from
the system linker. LTO support on Linux systems requires that you use the
`gold linker`_ which supports LTO via plugins. This is the same mechanism
used by the `GCC LTO`_ project.
The LLVM gold plugin implements the gold plugin interface on top of
:ref:`libLTO`. The same plugin can also be used by other tools such as
``ar`` and ``nm``.
.. _`gold linker`: http://sourceware.org/binutils
.. _`GCC LTO`: http://gcc.gnu.org/wiki/LinkTimeOptimization
.. _`gold plugin interface`: http://gcc.gnu.org/wiki/whopr/driver
.. _lto-how-to-build:
How to build it
===============
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.
* To build gold with plugin support:
.. code-block:: bash
$ 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 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. It also built would have
``binutils/build/binutils/ar`` and ``nm-new`` which support plugins but
don't have a visible -plugin option, instead relying on the gold plugin
being present in ``../lib/bfd-plugins`` relative to where the binaries
are placed.
* Build the LLVMgold plugin: Configure LLVM with
``--with-binutils-include=/path/to/binutils/src/include`` and run
``make``.
Usage
=====
The linker takes a ``-plugin`` option that points to the path of
the plugin ``.so`` file. To find out what link command ``gcc``
would run in a given situation, run ``gcc -v [...]`` and
look for the line where it runs ``collect2``. Replace that with
``ld-new -plugin /path/to/LLVMgold.so`` to test it out. Once you're
ready to switch to using gold, backup your existing ``/usr/bin/ld``
then replace it with ``ld-new``.
You can produce bitcode files from ``clang`` using ``-emit-llvm`` or
``-flto``, or the ``-O4`` flag which is synonymous with ``-O3 -flto``.
Any of these flags will also cause ``clang`` to look for the gold plugin in
the ``lib`` directory under its prefix and pass 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``
Example of link time optimization
---------------------------------
The following example shows a worked example of the gold plugin mixing LLVM
bitcode and native code.
.. code-block:: c
--- 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");
}
.. code-block:: bash
--- command lines ---
$ clang -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
$ clang b.c -c -o b.o # <-- b.o is native object file
$ clang -flto 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 :ref:`libLTO
example <libLTO-example>` gold does not currently eliminate foo4.
Quickstart for using LTO with autotooled projects
=================================================
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:
* Follow the instructions :ref:`on how to build LLVMgold.so
<lto-how-to-build>`.
* Install the newly built binutils to ``$PREFIX``
* Copy ``Release/lib/LLVMgold.so`` to ``$PREFIX/lib/bfd-plugins/``
* Set environment variables (``$PREFIX`` is where you installed clang and
binutils):
.. code-block:: bash
export CC="$PREFIX/bin/clang -flto"
export CXX="$PREFIX/bin/clang++ -flto"
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"
* Or you can just set your path:
.. code-block:: bash
export PATH="$PREFIX/bin:$PATH"
export CC="clang -flto"
export CXX="clang++ -flto"
export RANLIB=/bin/true
export CFLAGS="-O4"
* Configure and build the project as usual:
.. code-block:: bash
% ./configure && make && make check
The environment variable settings may work for non-autotooled projects too,
but you may need to set the ``LD`` environment variable as well.
Licensing
=========
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.

2
llvm/docs/LinkTimeOptimization.rst
View File

@ -29,6 +29,8 @@ bitcode files. This tight integration between the linker and LLVM optimizer
helps to do optimizations that are not possible in other models. The linker helps to do optimizations that are not possible in other models. The linker
input allows the optimizer to avoid relying on conservative escape analysis. input allows the optimizer to avoid relying on conservative escape analysis.
.. _libLTO-example:
Example of link time optimization Example of link time optimization
--------------------------------- ---------------------------------

3
llvm/docs/subsystems.rst
View File

@ -16,6 +16,7 @@ Subsystem Documentation
SegmentedStacks SegmentedStacks
TableGenFundamentals TableGenFundamentals
DebuggingJITedCode DebuggingJITedCode
GoldPlugin
* `Writing an LLVM Pass <WritingAnLLVMPass.html>`_ * `Writing an LLVM Pass <WritingAnLLVMPass.html>`_
@ -75,7 +76,7 @@ Subsystem Documentation
This document describes the interface between LLVM intermodular optimizer This document describes the interface between LLVM intermodular optimizer
and the linker and its design and the linker and its design
* `The LLVM gold plugin <GoldPlugin.html>`_ * :ref:`gold-plugin`
How to build your programs with link-time optimization on Linux. How to build your programs with link-time optimization on Linux.