</head>
<body>
-<div class="doc_title">
+<h1>
Getting Started with the LLVM System
-</div>
+</h1>
<ul>
<li><a href="#overview">Overview</a>
<li><a href="#environment">Setting Up Your Environment</a></li>
<li><a href="#unpack">Unpacking the LLVM Archives</a></li>
<li><a href="#checkout">Checkout LLVM from Subversion</a></li>
+ <li><a href="#git_mirror">LLVM GIT mirror</a></li>
<li><a href="#installcf">Install the GCC Front End</a></li>
<li><a href="#config">Local LLVM Configuration</a></li>
<li><a href="#compile">Compiling the LLVM Suite Source Code</a></li>
<li><a href="#test-suite"><tt>test-suite</tt></a></li>
<li><a href="#tools"><tt>llvm/tools</tt></a></li>
<li><a href="#utils"><tt>llvm/utils</tt></a></li>
- <li><a href="#win32"><tt>llvm/win32</tt></a></li>
</ol></li>
<li><a href="#tutorial">An Example Using the LLVM Tool Chain</a>
<p>Written by:
<a href="mailto:criswell@uiuc.edu">John Criswell</a>,
<a href="mailto:sabre@nondot.org">Chris Lattner</a>,
- <a href="http://misha.brukman.net">Misha Brukman</a>,
+ <a href="http://misha.brukman.net/">Misha Brukman</a>,
<a href="http://www.cs.uiuc.edu/~vadve">Vikram Adve</a>, and
<a href="mailto:gshi1@uiuc.edu">Guochun Shi</a>.
</p>
<!-- *********************************************************************** -->
-<div class="doc_section">
- <a name="overview"><b>Overview</b></a>
-</div>
+<h2>
+ <a name="overview">Overview</a>
+</h2>
<!-- *********************************************************************** -->
-<div class="doc_text">
+<div>
<p>Welcome to LLVM! In order to get started, you first need to know some
basic information.</p>
</div>
<!-- *********************************************************************** -->
-<div class="doc_section">
- <a name="quickstart"><b>Getting Started Quickly (A Summary)</b></a>
-</div>
+<h2>
+ <a name="quickstart">Getting Started Quickly (A Summary)</a>
+</h2>
<!-- *********************************************************************** -->
-<div class="doc_text">
+<div>
<p>Here's the short story for getting up and running quickly with LLVM:</p>
<li>Read the documentation.</li>
<li>Remember that you were warned twice about reading the documentation.</li>
<li>Install the llvm-gcc-4.2 front end if you intend to compile C or C++
- (see <a href="#installcf">Install the GCC Front End</a> for details):</li>
+ (see <a href="#installcf">Install the GCC Front End</a> for details):
<ol>
<li><tt>cd <i>where-you-want-the-C-front-end-to-live</i></tt></li>
<li><tt>gunzip --stdout llvm-gcc-4.2-<i>version</i>-<i>platform</i>.tar.gz | tar -xvf -</tt></li>
<li><tt><i>install-binutils-binary-from-MinGW</i></tt> (Windows only)</li>
<li>Note: If the binary extension is "<tt>.bz</tt>" use <tt>bunzip2</tt> instead of <tt>gunzip</tt>.</li>
- <li>Note: On Windows, use <a href="http://www.7-zip.org">7-Zip</a> or a similar archiving tool.</li>
+ <li>Note: On Windows, use <a href="http://www.7-zip.org/">7-Zip</a> or a similar archiving tool.</li>
<li>Add <tt>llvm-gcc</tt>'s "<tt>bin</tt>" directory to your <tt>PATH</tt> environment variable.</li>
</ol></li>
</div>
<!-- *********************************************************************** -->
-<div class="doc_section">
- <a name="requirements"><b>Requirements</b></a>
-</div>
+<h2>
+ <a name="requirements">Requirements</a>
+</h2>
<!-- *********************************************************************** -->
-<div class="doc_text">
+<div>
<p>Before you begin to use the LLVM system, review the requirements given below.
This may save you some trouble by knowing ahead of time what hardware and
software you will need.</p>
-</div>
-
<!-- ======================================================================= -->
-<div class="doc_subsection">
- <a name="hardware"><b>Hardware</b></a>
-</div>
+<h3>
+ <a name="hardware">Hardware</a>
+</h3>
-<div class="doc_text">
+<div>
<p>LLVM is known to work on the following platforms:</p>
<td>x86<sup><a href="#pf_1">1</a></sup></td>
<td>GCC</td>
</tr>
+<tr>
+ <td>FreeBSD</td>
+ <td>amd64</td>
+ <td>GCC</td>
+</tr>
<tr>
<td>MacOS X<sup><a href="#pf_2">2</a></sup></td>
<td>PowerPC</td>
<tr>
<td>MinGW/Win32</td>
<td>x86<sup><a href="#pf_1">1</a>,<a href="#pf_6">6</a>,
- <a href="#pf_8">8</a>, <a href="#pf_10">10</a></sup></td>
+ <a href="#pf_8">8</a>, <a href="#pf_10">10</a>,
+ <a href="#pf_11">11</a></sup></td>
<td>GCC 3.4.X, binutils 2.20</td>
</tr>
</table>
<td>Itanium (IA-64)</td>
<td>HP aCC</td>
</tr>
+<tr>
+ <td>Windows x64</td>
+ <td>x86-64</td>
+ <td>mingw-w64's GCC-4.5.x<sup><a href="#pf_12">12</a></sup></td>
+</tr>
</table>
<p><b>Notes:</b></p>
before any Windows-based versions such as Strawberry Perl and
ActivePerl, as these have Windows-specifics that will cause the
build to fail.</a></li>
-<li><a name="pf_11">In general, LLVM modules requiring dynamic linking can
- not be built on Windows. However, you can build LLVM tools using
- <i>"make tools-only"</i>.</li>
+<li><a name="pf_11">To use LLVM modules on Win32-based system,
+ you may configure LLVM with <i>"--enable-shared"</i>.</a></li>
+<li><a name="pf_12">To compile SPU backend, you need to add
+ <tt>"LDFLAGS=-Wl,--stack,16777216"</tt> to configure.</a></li>
</ol>
</div>
</div>
<!-- ======================================================================= -->
-<div class="doc_subsection"><a name="software"><b>Software</b></a></div>
-<div class="doc_text">
+<h3>
+ <a name="software">Software</a>
+</h3>
+<div>
<p>Compiling LLVM requires that you have several software packages
installed. The table below lists those required packages. The Package column
is the usual name for the software package that LLVM depends on. The Version
</tr>
<tr>
- <td><a href="http://gcc.gnu.org">GCC</a></td>
+ <td><a href="http://gcc.gnu.org/">GCC</a></td>
<td>3.4.2</td>
<td>C/C++ compiler<sup><a href="#sf1">1</a></sup></td>
</tr>
<tr>
- <td><a href="http://www.gnu.org/software/texinfo">TeXinfo</a></td>
+ <td><a href="http://www.gnu.org/software/texinfo/">TeXinfo</a></td>
<td>4.5</td>
<td>For building the CFE</td>
</tr>
<td>Subversion access to LLVM<sup><a href="#sf2">2</a></sup></td>
</tr>
+ <!-- FIXME:
+ Do we support dg?
+ Are DejaGnu and expect obsolete?
+ Shall we mention Python? -->
+
<tr>
<td><a href="http://savannah.gnu.org/projects/dejagnu">DejaGnu</a></td>
<td>1.4.2</td>
</tr>
<tr>
- <td><a href="http://www.gnu.org/software/autoconf">GNU Autoconf</a></td>
+ <td><a href="http://www.gnu.org/software/autoconf/">GNU Autoconf</a></td>
<td>2.60</td>
<td>Configuration script builder<sup><a href="#sf4">4</a></sup></td>
</tr>
<tr>
- <td><a href="http://www.gnu.org/software/automake">GNU Automake</a></td>
+ <td><a href="http://www.gnu.org/software/automake/">GNU Automake</a></td>
<td>1.9.6</td>
<td>aclocal macro generator<sup><a href="#sf4">4</a></sup></td>
</tr>
</div>
<!-- ======================================================================= -->
-<div class="doc_subsection">
+<h3>
<a name="brokengcc">Broken versions of GCC and other tools</a>
-</div>
+</h3>
-<div class="doc_text">
+<div>
<p>LLVM is very demanding of the host C++ compiler, and as such tends to expose
bugs in the compiler. In particular, several versions of GCC crash when trying
<p><b>GCC 4.3.3 (Debian 4.3.3-10) on ARM</b>: Miscompiles parts of LLVM 2.6
when optimizations are turned on. The symptom is an infinite loop in
FoldingSetImpl::RemoveNode while running the code generator.</p>
+<p><b>GCC 4.3.5 and GCC 4.4.5 on ARM</b>: These can miscompile <tt>value >>
+1</tt> even at -O0. A test failure in <tt>test/Assembler/alignstack.ll</tt> is
+one symptom of the problem.
<p><b>GNU ld 2.16.X</b>. Some 2.16.X versions of the ld linker will produce very
long warning messages complaining that some ".gnu.linkonce.t.*" symbol was
defined in a discarded section. You can safely ignore these messages as they are
</div>
-
+</div>
<!-- *********************************************************************** -->
-<div class="doc_section">
- <a name="starting"><b>Getting Started with LLVM</b></a>
-</div>
+<h2>
+ <a name="starting">Getting Started with LLVM</a>
+</h2>
<!-- *********************************************************************** -->
-<div class="doc_text">
+<div>
<p>The remainder of this guide is meant to get you up and running with
LLVM and to give you some basic information about the LLVM environment.</p>
href="#tutorial">simple example</a> using the LLVM tool chain, and <a
href="#links">links</a> to find more information about LLVM or to get
help via e-mail.</p>
-</div>
<!-- ======================================================================= -->
-<div class="doc_subsection">
+<h3>
<a name="terminology">Terminology and Notation</a>
-</div>
+</h3>
-<div class="doc_text">
+<div>
<p>Throughout this manual, the following names are used to denote paths
specific to the local system and working environment. <i>These are not
</div>
<!-- ======================================================================= -->
-<div class="doc_subsection">
+<h3>
<a name="environment">Setting Up Your Environment</a>
-</div>
+</h3>
-<div class="doc_text">
+<div>
<p>
In order to compile and use LLVM, you may need to set some environment
</div>
<!-- ======================================================================= -->
-<div class="doc_subsection">
+<h3>
<a name="unpack">Unpacking the LLVM Archives</a>
-</div>
+</h3>
-<div class="doc_text">
+<div>
<p>
If you have the LLVM distribution, you will need to unpack it before you
</div>
<!-- ======================================================================= -->
-<div class="doc_subsection">
+<h3>
<a name="checkout">Checkout LLVM from Subversion</a>
-</div>
+</h3>
-<div class="doc_text">
+<div>
<p>If you have access to our Subversion repository, you can get a fresh copy of
the entire source code. All you need to do is check it out from Subversion as
subdirectories of the '<tt>tags</tt>' directory:</p>
<ul>
+<li>Release 2.9: <b>RELEASE_29/final</b></li>
<li>Release 2.8: <b>RELEASE_28</b></li>
<li>Release 2.7: <b>RELEASE_27</b></li>
<li>Release 2.6: <b>RELEASE_26</b></li>
</div>
<!-- ======================================================================= -->
-<div class="doc_subsection">
- <a name="installcf">Install the GCC Front End</a>
+<h3>
+ <a name="git_mirror">GIT mirror</a>
+</h3>
+
+<div>
+
+<p>GIT mirrors are available for a number of LLVM subprojects. These mirrors
+ sync automatically with each Subversion commit and contain all necessary
+ git-svn marks (so, you can recreate git-svn metadata locally). Note that right
+ now mirrors reflect only <tt>trunk</tt> for each project. You can do the
+ read-only GIT clone of LLVM via:</p>
+
+<pre class="doc_code">
+git clone http://llvm.org/git/llvm.git
+</pre>
+
+<p>If you want to check out clang too, run:</p>
+
+<pre class="doc_code">
+git clone http://llvm.org/git/llvm.git
+cd llvm/tools
+git clone http://llvm.org/git/clang.git
+</pre>
+
+<p>To set up clone from which you can submit code using
+ <tt>git-svn</tt>, run:</p>
+
+<pre class="doc_code">
+git clone http://llvm.org/git/llvm.git
+cd llvm
+git svn init https://llvm.org/svn/llvm-project/llvm/trunk --username=<username>
+git config svn-remote.svn.fetch :refs/remotes/origin/master
+git svn rebase -l # -l avoids fetching ahead of the git mirror.
+
+# If you have clang too:
+cd tools
+git clone http://llvm.org/git/clang.git
+cd clang
+git svn init https://llvm.org/svn/llvm-project/cfe/trunk --username=<username>
+git config svn-remote.svn.fetch :refs/remotes/origin/master
+git svn rebase -l
+</pre>
+
+<p>To update this clone without generating git-svn tags that conflict
+with the upstream git repo, run:</p>
+
+<pre class="doc_code">
+git fetch && (cd tools/clang && git fetch) # Get matching revisions of both trees.
+git checkout master
+git svn rebase -l
+(cd tools/clang &&
+ git checkout master &&
+ git svn rebase -l)
+</pre>
+
+<p>This leaves your working directories on their master branches, so
+you'll need to <tt>checkout</tt> each working branch individually and
+<tt>rebase</tt> it on top of its parent branch. (Note: This script is
+intended for relative newbies to git. If you have more experience,
+you can likely improve on it.)</p>
+
+<p>The git-svn metadata can get out of sync after you mess around with
+branches and <code>dcommit</code>. When that happens, <code>git svn
+dcommit</code> stops working, complaining about files with uncommitted
+changes. The fix is to rebuild the metadata:</p>
+
+<pre class="doc_code">
+rm -rf .git/svn
+git svn rebase -l
+</pre>
+
</div>
-<div class="doc_text">
+<!-- ======================================================================= -->
+<h3>
+ <a name="installcf">Install the GCC Front End</a>
+</h3>
+
+<div>
<p>Before configuring and compiling the LLVM suite (or if you want to use just the LLVM
GCC front end) you can optionally extract the front end from the binary distribution.
main LLVM repository.</p>
<p>To install the GCC front end, do the following (on Windows, use an archival tool
-like <a href="http://www.7-zip.org">7-zip</a> that understands gzipped tars):</p>
+like <a href="http://www.7-zip.org/">7-zip</a> that understands gzipped tars):</p>
<ol>
<li><tt>cd <i>where-you-want-the-front-end-to-live</i></tt></li>
</div>
<!-- ======================================================================= -->
-<div class="doc_subsection">
+<h3>
<a name="config">Local LLVM Configuration</a>
-</div>
+</h3>
-<div class="doc_text">
+<div>
<p>Once checked out from the Subversion repository, the LLVM suite source
code must be
</div>
<!-- ======================================================================= -->
-<div class="doc_subsection">
+<h3>
<a name="compile">Compiling the LLVM Suite Source Code</a>
-</div>
+</h3>
-<div class="doc_text">
+<div>
<p>Once you have configured LLVM, you can build it. There are three types of
builds:</p>
</div>
<!-- ======================================================================= -->
-<div class="doc_subsection">
+<h3>
<a name="cross-compile">Cross-Compiling LLVM</a>
-</div>
+</h3>
-<div class="doc_text">
+<div>
<p>It is possible to cross-compile LLVM itself. That is, you can create LLVM
executables and libraries to be hosted on a platform different from the
platform where they are build (a Canadian Cross build). To configure a
</div>
<!-- ======================================================================= -->
-<div class="doc_subsection">
+<h3>
<a name="objfiles">The Location of LLVM Object Files</a>
-</div>
+</h3>
-<div class="doc_text">
+<div>
<p>The LLVM build system is capable of sharing a single LLVM source tree among
several LLVM builds. Hence, it is possible to build LLVM for several different
</div>
<!-- ======================================================================= -->
-<div class="doc_subsection">
+<h3>
<a name="optionalconfig">Optional Configuration Items</a>
-</div>
+</h3>
-<div class="doc_text">
+<div>
<p>
If you're running on a Linux system that supports the "<a
<p>
This allows you to execute LLVM bitcode files directly. On Debian, you
-can also use this command instead of the 'echo' command above:</p>
+can also use this command instead of the 'echo' command above:
</p>
<div class="doc_code">
</div>
-<!-- *********************************************************************** -->
-<div class="doc_section">
- <a name="layout"><b>Program Layout</b></a>
</div>
+
+<!-- *********************************************************************** -->
+<h2>
+ <a name="layout">Program Layout</a>
+</h2>
<!-- *********************************************************************** -->
-<div class="doc_text">
+<div>
<p>One useful source of information about the LLVM source base is the LLVM <a
-href="http://www.doxygen.org">doxygen</a> documentation available at <tt><a
+href="http://www.doxygen.org/">doxygen</a> documentation available at <tt><a
href="http://llvm.org/doxygen/">http://llvm.org/doxygen/</a></tt>.
The following is a brief introduction to code layout:</p>
-</div>
-
<!-- ======================================================================= -->
-<div class="doc_subsection"><a name="examples"><tt>llvm/examples</tt></a></div>
-<div class="doc_text">
+<h3>
+ <a name="examples"><tt>llvm/examples</tt></a>
+</h3>
+
+<div>
<p>This directory contains some simple examples of how to use the LLVM IR and
JIT.</p>
</div>
<!-- ======================================================================= -->
-<div class="doc_subsection"><a name="include"><tt>llvm/include</tt></a></div>
-<div class="doc_text">
+<h3>
+ <a name="include"><tt>llvm/include</tt></a>
+</h3>
+
+<div>
<p>This directory contains public header files exported from the LLVM
library. The three main subdirectories of this directory are:</p>
</div>
<!-- ======================================================================= -->
-<div class="doc_subsection"><a name="lib"><tt>llvm/lib</tt></a></div>
-<div class="doc_text">
+<h3>
+ <a name="lib"><tt>llvm/lib</tt></a>
+</h3>
+
+<div>
<p>This directory contains most of the source files of the LLVM system. In LLVM,
almost all code exists in libraries, making it very easy to share code among the
<dd> This directory contains the major parts of the code generator: Instruction
Selector, Instruction Scheduling, and Register Allocation.</dd>
+ <dt><tt><b>llvm/lib/MC/</b></tt></dt>
+ <dd>(FIXME: T.B.D.)</dd>
+
+ <!--FIXME: obsoleted -->
<dt><tt><b>llvm/lib/Debugger/</b></tt></dt>
<dd> This directory contains the source level debugger library that makes
it possible to instrument LLVM programs so that a debugger could identify
<dd> This directory contains the source code that corresponds to the header
files located in <tt>llvm/include/Support/</tt>.</dd>
+ <!--FIXME: obsoleted -->
<dt><tt><b>llvm/lib/System/</b></tt></dt>
<dd>This directory contains the operating system abstraction layer that
shields LLVM from platform-specific coding.</dd>
</div>
<!-- ======================================================================= -->
-<div class="doc_subsection"><a name="projects"><tt>llvm/projects</tt></a></div>
-<div class="doc_text">
+<h3>
+ <a name="projects"><tt>llvm/projects</tt></a>
+</h3>
+
+<div>
<p>This directory contains projects that are not strictly part of LLVM but are
shipped with LLVM. This is also the directory where you should create your own
LLVM-based projects. See <tt>llvm/projects/sample</tt> for an example of how
</div>
<!-- ======================================================================= -->
-<div class="doc_subsection"><a name="runtime"><tt>llvm/runtime</tt></a></div>
-<div class="doc_text">
+<h3>
+ <a name="runtime"><tt>llvm/runtime</tt></a>
+</h3>
+
+<div>
<p>This directory contains libraries which are compiled into LLVM bitcode and
used when linking programs with the GCC front end. Most of these libraries are
</div>
<!-- ======================================================================= -->
-<div class="doc_subsection"><a name="test"><tt>llvm/test</tt></a></div>
-<div class="doc_text">
+<h3>
+ <a name="test"><tt>llvm/test</tt></a>
+</h3>
+
+<div>
<p>This directory contains feature and regression tests and other basic sanity
checks on the LLVM infrastructure. These are intended to run quickly and cover
a lot of territory without being exhaustive.</p>
</div>
<!-- ======================================================================= -->
-<div class="doc_subsection"><a name="test-suite"><tt>test-suite</tt></a></div>
-<div class="doc_text">
+<h3>
+ <a name="test-suite"><tt>test-suite</tt></a>
+</h3>
+
+<div>
<p>This is not a directory in the normal llvm module; it is a separate
Subversion
module that must be checked out (usually to <tt>projects/test-suite</tt>).
</div>
<!-- ======================================================================= -->
-<div class="doc_subsection"><a name="tools"><tt>llvm/tools</tt></a></div>
-<div class="doc_text">
+<h3>
+ <a name="tools"><tt>llvm/tools</tt></a>
+</h3>
+
+<div>
<p>The <b>tools</b> directory contains the executables built out of the
libraries above, which form the main part of the user interface. You can
</div>
<!-- ======================================================================= -->
-<div class="doc_subsection"><a name="utils"><tt>llvm/utils</tt></a></div>
-<div class="doc_text">
+<h3>
+ <a name="utils"><tt>llvm/utils</tt></a>
+</h3>
+
+<div>
<p>This directory contains utilities for working with LLVM source code, and some
of the utilities are actually required as part of the build process because they
</div>
-<!-- ======================================================================= -->
-<div class="doc_subsection"><a name="win32"><tt>llvm/win32</tt></a></div>
-<div class="doc_text">
- <p>This directory contains build scripts and project files for use with
- Visual C++. This allows developers on Windows to build LLVM without the need
- for Cygwin. The contents of this directory should be considered experimental
- at this time.
- </p>
</div>
+
<!-- *********************************************************************** -->
-<div class="doc_section">
+<h2>
<a name="tutorial">An Example Using the LLVM Tool Chain</a>
-</div>
+</h2>
<!-- *********************************************************************** -->
-<div class="doc_text">
+<div>
<p>This section gives an example of using LLVM. llvm-gcc3 is now obsolete,
so we only include instructions for llvm-gcc4.
</p>
the '--emit-llvm' flag is needed to produce LLVM bitcode output. For <i>makefiles</i> and
<i>configure</i> scripts, the CFLAGS variable needs '--emit-llvm' to produce bitcode
output.</p>
-</div>
<!-- ======================================================================= -->
-<div class="doc_subsection"><a name="tutorial4">Example with llvm-gcc4</a></div>
+<h3>
+ <a name="tutorial4">Example with llvm-gcc4</a>
+</h3>
-<div class="doc_text">
+<div>
<ol>
<li><p>First, create a simple C file, name it 'hello.c':</p>
</div>
+</div>
<!-- *********************************************************************** -->
-<div class="doc_section">
+<h2>
<a name="problems">Common Problems</a>
-</div>
+</h2>
<!-- *********************************************************************** -->
-<div class="doc_text">
+<div>
<p>If you are having problems building or using LLVM, or if you have any other
general questions about LLVM, please consult the <a href="FAQ.html">Frequently
</div>
<!-- *********************************************************************** -->
-<div class="doc_section">
+<h2>
<a name="links">Links</a>
-</div>
+</h2>
<!-- *********************************************************************** -->
-<div class="doc_text">
+<div>
<p>This document is just an <b>introduction</b> on how to use LLVM to do
some simple things... there are many more interesting and complicated things
<a href="mailto:sabre@nondot.org">Chris Lattner</a><br>
<a href="http://llvm.x10sys.com/rspencer/">Reid Spencer</a><br>
- <a href="http://llvm.org">The LLVM Compiler Infrastructure</a><br>
+ <a href="http://llvm.org/">The LLVM Compiler Infrastructure</a><br>
Last modified: $Date$
</address>
</body>