</head>
<body bgcolor=white>
- <h1>Getting Started with the LLVM System<br><font size=3>By: <a
- href="mailto:gshi1@uiuc.edu">Guochun Shi</a> and <a
- href="mailto:sabre@nondot.org">Chris Lattner</a></font></h1>
+ <center><h1>Getting Started with the LLVM System<br><font size=3>By: <a
+ href="mailto:gshi1@uiuc.edu">Guochun Shi</a>,
+ <a href="mailto:sabre@nondot.org">Chris Lattner</a> and
+ <a href="http://www.cs.uiuc.edu/~vadve">Vikram Adve</a>
+ </font></h1></center>
+
+ <!--=====================================================================-->
+ <h2><a name="Contents">Contents</a></h2>
+ <!--=====================================================================-->
<ul>
- <li><a href="#quickstart">Getting started with LLVM</a>
+ <li><a href="#overview">Overview</a>
+ <li><a href="#starting">Getting started with LLVM</a>
<ol>
- <li><a href="#cvs">Checkout LLVM from CVS</a>
- <li><a href="#environment">Set up your environment</a>
- <li><a href="#compile">Compiling the Source Code</a>
+ <li><a href="#quickstart">Getting started quickly (a summary)</a>
+ <li><a href="#checkout">Checkout LLVM from CVS</a>
+ <li><a href="#terminology">Terminology and Notation</tt></a>
+ <li><a href="#objfiles">The location for object files</tt></a>
+ <li><a href="#config">Local Configuration Options</tt></a>
+ <li><a href="#environment">Setting up your environment</a>
+ <li><a href="#compile">Compiling the source code</a>
</ol>
<li><a href="#layout">Program layout</a>
<ol>
<li><a href="#cvsdir">CVS directories</a>
- <li><a href="#dd">Depend, Debug, & Release directories</a></li>
- <li><a href="#include">llvm/include</a>
- <li><a href="#lib">llvm/lib</a>
- <li><a href="#test">llvm/test</a>
- <li><a href="#tools">llvm/tools</a>
+ <li><a href="#dd"><tt>Depend</tt>, <tt>Debug</tt>, &
+ <tt>Release</tt> directories</a></li>
+ <li><a href="#include"><tt>llvm/include</tt></a>
+ <li><a href="#lib"><tt>llvm/lib</tt></a>
+ <li><a href="#test"><tt>llvm/test</tt></a>
+ <li><a href="#tools"><tt>llvm/tools</tt></a>
</ol>
<li><a href="#tutorial">An example using the LLVM tool chain</a>
<li><a href="#links">Links</a>
</ul>
+ <!--=====================================================================-->
+ <center>
+ <h2><a name="overview"><b>Overview</b></a></h2>
+ </center>
+ <!--=====================================================================-->
+
+ <p>The <a href"starting">next section</a> of this guide is meant to get
+ you up and running with LLVM, and to give you some basic information about
+ the LLVM environment. The <a href"#quickstart">first subsection</a> gives
+ a short summary for those who are already familiar with the system and
+ want to get started as quickly as possible.
+
+ <p>The later sections of this guide describe the <a
+ href"#layout">general layout</a> of the the LLVM source-tree, a <a
+ 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.
<!--=====================================================================-->
- <h2><a name="quickstart">Getting Started with LLVM</a></h2>
+ <center>
+ <h2><a name="starting"><b>Getting Started</b></a></h2>
+ </center>
<!--=====================================================================-->
- <p>This guide is meant to get you up and running with LLVM as quickly as
- possible. Once you get the basic system running you can choose an area to
- dive into and learn more about. If you get stuck or something is missing
- from this document, please email <a
- href="mailto:sabre@nondot.org">Chris</a>.</p>
-
+
+ <!--=====================================================================-->
+ <h3><a name="quickstart"><b>Getting Started Quickly (A Summary)</b></a></h3>
+ <!--=====================================================================-->
+
+ Here's the short story for getting up and running quickly with LLVM:
+ <ul>
+ <li>Find the path to the CVS repository containing LLVM (we'll call this <i>CVSROOTDIR</i>).
+ <li><tt>cd <i>where-you-want-llvm-to-live</i></tt>
+ <li><tt>cvs -d <i>CVSROOTDIR</i> checkout llvm</tt>
+ <li>Edit <tt>llvm/Makefile.config</tt> to set local paths if necessary.
+ <li><tt>cd llvm</tt>
+ <li><tt>gmake -k |& tee gnumake.out
+ # this is csh or tcsh syntax</tt>
+ </ul>
+
+ <p>See <a href="#environment">Setting up your environment</a> on tips to
+ simplify working with the LLVM front-end and compiled tools. See the
+ other sub-sections below for other useful details in working with LLVM,
+ or go straight to <a href="#layout">Program Layout</a> to learn about the
+ layout of the source code tree.
<!------------------------------------------------------------------------->
- <h3><a name="tools">Checkout LLVM from CVS</a></h3>
+ <h3><a name="terminology">Terminology and Notation</a></h3>
<!------------------------------------------------------------------------->
- <p>First step is to get the actual source code. To do this, all you need to
- do is check it out from CVS. From your home directory, just enter:</p>
+ <p>Through this manual, the following names are used to denote paths
+ specific to the local system and working environment. <i>These are not
+ environment variables you need to set, but just strings used in the rest
+ of this document below.</i>. In any of the examples below, simply replace
+ each of these names with the appropriate pathname on your local system.
+ All these paths are absolute:</p>
+ <ul>
+ </ul>
- <p><tt>cvs -d /home/vadve/vadve/Research/DynOpt/CVSRepository checkout llvm</tt></p>
+ <!------------------------------------------------------------------------->
+ <h3><a name="checkout">Checkout LLVM from CVS</a></h3>
+ <!------------------------------------------------------------------------->
- <p>This will create an '<tt>llvm</tt>' directory in your home directory and fully
- populate it with the source code for LLVM.</p>
-
+ <p>Before checking out the source code, you will need to know the path to
+ CVS repository containing LLVM source code (we'll call this
+ <i>CVSROOTDIR</i> below). Ask the person responsible for your local LLVM
+ installation to give you this path.
+
+ <p>To get a fresh copy of the entire source code, all you
+ need to do is check it out from CVS as follows:
+ <ul>
+ <li><tt>cd <i>where-you-want-llvm-to-live</i></tt>
+ <li><tt>cvs -d <i>CVSROOTDIR</i> checkout llvm</tt></p>
+ </ul>
+
+ <p>This will create an '<tt>llvm</tt>' directory in the current
+ directory and fully populate it with the LLVM source code, Makefiles,
+ test directories, and local copies of documentation files.</p>
<!------------------------------------------------------------------------->
- <h3><a name="tools">Set up your environment</a></h3>
+ <h3><a name="config">Local Configuration Options</a></h3>
<!------------------------------------------------------------------------->
-
- <p>Now that you have the source code available, you should set up your
- environment to be able to use the LLVM tools (once compiled) with as little
- hassle as possible. To do this, we recommend that you add the following
- lines to your <tt>.cshrc</tt> (or the corresponding lines to your
- <tt>.profile</tt> if you use a bourne shell derivative):
- <pre>
- # Make the C frontend easy to use...
- alias llvmgcc /home/vadve/lattner/cvs/gcc_install/bin/gcc
+ <p>The file <tt>llvm/Makefile.config</tt>
+ defines the following path variables,
+ which are specific to a particular installation of LLVM.
+ These should need to be modified only once after checking out a copy
+ of LLVM (if the default values do not already match your system):
- # Make the LLVM tools easy to use...
- setenv PATH ~/llvm/tools/Debug:${PATH}
- </pre>
+ <ul>
+ <p><li><i>CXX</i> = Path to C++ compiler to use.
+ <p><li><i>LLVM_OBJ_DIR</i> = Path to the llvm directory where
+ object files should be placed.
+ (See the Section on <a href=#objfiles>
+ The location for LLVM object files</a>
+ for more information.)
+ <p><li><i>LLVMGCCDIR</i> = Path to the location of the LLVM front-end
+ binaries and associated libraries.
+ <p><li><i>PURIFY</i> = Path to the purify program.
+ </ul>
+
+ <!------------------------------------------------------------------------->
+ <h3><a name="objfiles">The location for LLVM object files</a></h3>
+ <!------------------------------------------------------------------------->
+
+ <p>The LLVM make system sends most output files generated during the build
+ into the directory defined by the variable LLVM_OBJ_DIR in
+ <tt>llvm/Makefile.config</tt>. This can be either just your normal LLVM
+ source tree or some other directory writable by you. You may wish to put
+ object files on a different filesystem either to keep them from being backed
+ up or to speed up local builds.
- <p>The C compiler is not included in the CVS tree you just checked out, so
- we just point to the cannonical location, and access it with the
- <tt>llvmgcc</tt> command. The rest of the <a href="#tools">LLVM tools</a>
- will be built into the llvm/tools/Debug directory inside of the sourcebase.
- Adding them to your path will make it much easier to use them.</p>
+ <p>If you do not wish to use a different location for object files (building
+ into the source tree directly), just set this variable to ".".<p>
+ <!------------------------------------------------------------------------->
+ <h3><a name="environment">Setting up your environment</a></h3>
+ <!------------------------------------------------------------------------->
+
+ <i>NOTE: This step is optional but will set up your environment so you
+ can use the compiled LLVM tools with as little hassle as
+ possible.</i>)
+ <p>Add the following lines to your <tt>.cshrc</tt> (or the corresponding
+ lines to your <tt>.profile</tt> if you use a bourne shell derivative).
+
+ <pre>
+ # Make the C front end easy to use...
+ alias llvmgcc <i>LLVMGCCDIR</i><tt>/bin/llvm-gcc</tt>
+
+ # Make the LLVM tools easy to use...
+ setenv PATH <i>LLVM_OBJ_DIR</i>/tools/Debug:${PATH}
+ </pre>
+ The <tt>llvmgcc</tt> alias is useful because the C compiler is not
+ included in the CVS tree you just checked out.
+
+ <p>The other <a href="#tools">LLVM tools</a> are part of the LLVM
+ source base, and built when compiling LLVM. They will be built into the
+ <tt><i>LLVM_OBJ_DIR</i>/tools/Debug</tt> directory.</p>
<!------------------------------------------------------------------------->
- <h3><a name="compile">Compiling the Source Code</a></h3>
+ <h3><a name="compile">Compiling the source code</a></h3>
<!------------------------------------------------------------------------->
- <p>Every directory in the LLVM source tree includes a Makefile to build it,
- and any subdirectories that it contains. These makefiles require that you
- use <tt>gmake</tt>, instead of <tt>make</tt> to build them, but can
+ <p>Every directory in the LLVM source tree includes a <tt>Makefile</tt> to
+ build it, and any subdirectories that it contains. These makefiles require
+ that you use <tt>gmake</tt>, instead of <tt>make</tt> to build them, but can
otherwise be used freely. To build the entire LLVM system, just enter the
top level <tt>llvm</tt> directory and type <tt>gmake</tt>. A few minutes
later you will hopefully have a freshly compiled toolchain waiting for you
in <tt>llvm/tools/Debug</tt>. If you want to look at the libraries that
were compiled, look in <tt>llvm/lib/Debug</tt>.</p>
+ If you get an error talking about a <tt>/localhome</tt> directory, follow
+ the instructions in the section about <a href="#environment">Setting Up Your
+ Environment.</a>
+
+
<!--=====================================================================-->
- <h2><a name="layout">Program Layout</a></h2>
+ <center>
+ <h2><a name="layout"><b>Program Layout</b></a></h2>
+ </center>
<!--=====================================================================-->
- <p>One useful source of infomation about the LLVM sourcebase is the LLVM
-
doxygen documentation, available at <tt><a
+ <p>One useful source of infomation about the LLVM sourcebase is the LLVM <a
+
href="http://www.doxygen.org">doxygen</a> documentation, available at <tt><a
href="http://llvm.cs.uiuc.edu/doxygen/">http://llvm.cs.uiuc.edu/doxygen/</a></tt>. The
following is a brief introduction to code layout:</p>
<!------------------------------------------------------------------------->
- <h3><a name="cvsdir">CVS directories</a></h3>
+ <h3><a name="cvsdir"><tt>CVS</tt> directories</a></h3>
<!------------------------------------------------------------------------->
- Every directory checked out of CVS will contain a CVS directory, for the
- most part these can just be ignored.
+ Every directory checked out of CVS will contain a <tt>CVS</tt> directory,
+ for the most part these can just be ignored.
<!------------------------------------------------------------------------->
- <h3><a name="ddr">Depend, Debug, & Release directories</a></h3>
+ <h3><a name="ddr"><tt>Depend</tt>, <tt>Debug</tt>, & <tt>Release</tt>
+ directories</a></h3>
<!------------------------------------------------------------------------->
- Most source directories contain two directories, Depend and Debug. The
- Depend directory contains automatically generated dependance files which are
- used during compilation to make sure that source files get rebuilt if a
- header file they use is modified. The Debug directory holds the object
+ If you are building with the "<tt>BUILD_ROOT=.</tt>" option enabled in the
+ <tt>Makefile.common</tt> file, most source directories will contain two
+ directories, <tt>Depend</tt> and <tt>Debug</tt>. The <tt>Depend</tt>
+ directory contains automatically generated dependance files which are used
+ during compilation to make sure that source files get rebuilt if a header
+ file they use is modified. The <tt>Debug</tt> directory holds the object
files, library files and executables that are used for building a debug
- enabled build. The Release directory is created to hold the same files when
- the <tt>ENABLE_OPTIMIZED=1</tt> flag is passed to <tt>gmake</tt>, causing an
- optimized built to be performed.
+ enabled build. The <tt>Release</tt> directory is created to hold the same
+ files when the <tt>ENABLE_OPTIMIZED=1</tt> flag is passed to <tt>gmake</tt>,
+ causing an optimized built to be performed.<p>
<!------------------------------------------------------------------------->
- <h3><a name="include">llvm/include</a></h3>
+ <h3><a name="include"><tt>llvm/include</tt></a></h3>
<!------------------------------------------------------------------------->
This directory contains public header files exported from the LLVM
- library. The two main subdirectories of this directory are:
+ library. The two main subdirectories of this directory are:<p>
<ol>
<li><tt>llvm/include/llvm</tt> - This directory contains all of the LLVM
specific header files. This directory also has subdirectories for
- different portions of llvm: <tt>Analysis</tt>, <tt>CodeGen</tt>,
+ different portions of LLVM: <tt>Analysis</tt>, <tt>CodeGen</tt>,
<tt>Reoptimizer</tt>, <tt>Target</tt>, <tt>Transforms</tt>, etc...
<li><tt>llvm/include/Support</tt> - This directory contains generic
</ol>
<!------------------------------------------------------------------------->
- <h3><a name="lib">llvm/lib</a></h3>
+ <h3><a name="lib"><tt>llvm/lib</tt></a></h3>
<!------------------------------------------------------------------------->
This directory contains most source files of LLVM system. In LLVM almost all
<dt><tt>llvm/lib/ByteCode/</tt><dd> This directory holds code for reading
and write LLVM bytecode.
- <dt><tt>llvm/lib/CWrite/</tt><dd> This directory implements the LLVM to C
+ <dt><tt>llvm/lib/CWriter/</tt><dd> This directory implements the LLVM to C
converter.
<dt><tt>llvm/lib/Analysis/</tt><dd> This directory contains a variety of
</dl>
<!------------------------------------------------------------------------->
- <h3><a name="test">llvm/test</a></h3>
+ <h3><a name="test"><tt>llvm/test</tt></a></h3>
<!------------------------------------------------------------------------->
<p>This directory contains regression tests and source code that is used to
test the LLVM infrastructure...</p>
<!------------------------------------------------------------------------->
- <h3><a name="tools">llvm/tools</a></h3>
+ <h3><a name="tools"><tt>llvm/tools</tt></a></h3>
<!------------------------------------------------------------------------->
<p>The <b>tools</b> directory contains the executables built out of the
<dl compact>
<dt><tt><b>as</b></tt><dd>The assembler transforms the human readable
-
llvm assembly to llvm bytecode.<p>
+
LLVM assembly to LLVM bytecode.<p>
- <dt><tt><b>dis</b></tt><dd>The disassembler transforms the llvm bytecode
- to human readable llvm assembly. Additionally it can convert LLVM
+ <dt><tt><b>dis</b></tt><dd>The disassembler transforms the LLVM bytecode
+ to human readable LLVM assembly. Additionally it can convert LLVM
bytecode to C, which is enabled with the <tt>-c</tt> option.<p>
<dt><tt><b>lli</b></tt><dd> <tt>lli</tt> is the LLVM interpreter, which
because it is quite large and not very interesting.<p>
<ol>
- <dt><tt><b>gccas</b></tt><dd> This took is invoked by the
+ <dt><tt><b>gccas</b></tt><dd> This tool is invoked by the
<tt>llvmgcc</tt> frontend as the "assembler" part of the compiler. This
- tool actually assembles its input, performs a variety of optimizations,
+ tool actually assembles LLVM assembly to LLVM bytecode,
+ performs a variety of optimizations,
and outputs LLVM bytecode. Thus when you invoke <tt>llvmgcc -c x.c -o
x.o</tt>, you are causing <tt>gccas</tt> to be run, which writes the
<tt>x.o</tt> file (which is an LLVM bytecode file that can be
frontend itself did not have to be modified to interface to a "wierd"
assembler.<p>
- <dt><tt><b>gccld</b></tt><dd> <tt>gccld</tt> links together several llvm
+ <dt><tt><b>gccld</b></tt><dd> <tt>gccld</tt> links together several LLVM
bytecode files into one bytecode file and does some optimization. It is
the linker invoked by the gcc frontend when multiple .o files need to be
linked together. Like <tt>gccas</tt> the command line interface of
interfacing with the GCC frontend.<p>
</ol>
- <dt><tt><b>opt</b></tt><dd> <tt>opt</tt> reads llvm bytecode, applies a
+ <dt><tt><b>opt</b></tt><dd> <tt>opt</tt> reads LLVM bytecode, applies a
series of LLVM to LLVM transformations (which are specified on the command
line), and then outputs the resultant bytecode. The '<tt>opt --help</tt>'
command is a good way to get a list of the program transformations
<hr>
If you have any questions or run into any snags (or you have any
- additions...), please send an email to <a
- href="mailto:sabre@nondot.org">Chris Lattner</a> or <a
- href="mailto:gshi1@uiuc.edu">Guochun Shi</a>. <p>
+ additions...), please send an email to
+ <a href="mailto:hldnbrnd@uiuc.edu">Nicholas Hildenbrandt</a> or
+ <a href="mailto:sabre@nondot.org">Chris Lattner</a>.</p>
<!-- Created: Mon Jul 1 02:29:02 CDT 2002 -->
<!-- hhmts start -->
-Last modified: Wed Jul 24 14:57:57 CDT 2002
+Last modified: Thu Sep 19 14:55:19 CDT 2002
<!-- hhmts end -->
</body>
</html>
projects / oota-llvm.git / blobdiff