docs/GettingStarted.html - fp2-dev/platform/external/llvm - Gitiles

 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
 <html>
   <head>
     <title>Getting Started with LLVM System</title>
   </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>

     <ul>
       <li><a href="#quickstart">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>
         </ol>
       <li><a href="#layout">Program layout</a>
 	<ol>
           <li><a href="#cvsdir">CVS directories</a>
 	  <li><a href="#dd"><tt>Depend</tt>, <tt>Debug</tt>, &amp;
                <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>


     <!--=====================================================================-->
     <h2><a name="quickstart">Getting Started with LLVM</a></h2>
     <!--=====================================================================-->

     <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="tools">Checkout LLVM from CVS</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><tt>cvs -d /home/vadve/vadve/Research/DynOpt/CVSRepository checkout
     llvm</tt></p>

     <p>This will create an '<tt>llvm</tt>' directory in your home directory and
     fully populate it with the source code for LLVM.</p>


     <!------------------------------------------------------------------------->
     <h3><a name="tools">Set up your environment</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

        # Make the LLVM tools easy to use...
        setenv PATH ~/llvm/tools/Debug:${PATH}
     </pre>

     <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 <tt>llvm/tools/Debug</tt> directory inside of the
     sourcebase.  Adding them to your path will make it much easier to use
     them.</p>


     <!------------------------------------------------------------------------->
     <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
     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>

     <p>By default, the LLVM build process sends all temporary (<tt>.o</tt>,
     <tt>.so</tt>, <tt>.a</tt>) files into a <tt>/shared/[your login
     name]/...</tt> directory, which is supposed to be on a disk local to the
     current machine.  If you get an error talking about a <tt>/shared</tt>
     directory, and you find out that it doesn't exist, try enabling the
     "<tt>BUILD_ROOT = .</tt> line in the top level <tt>Makefile.common</tt> that
     will change LLVM to build into the current directory instead of
     <tt>/shared</tt>.<p>


     <!--=====================================================================-->
     <h2><a name="layout">Program Layout</a></h2>
     <!--=====================================================================-->

     <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"><tt>CVS</tt> directories</a></h3>
     <!------------------------------------------------------------------------->

     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"><tt>Depend</tt>, <tt>Debug</tt>, &amp; <tt>Release</tt>
     directories</a></h3>
     <!------------------------------------------------------------------------->

     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 <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"><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:<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>,
        <tt>Reoptimizer</tt>, <tt>Target</tt>, <tt>Transforms</tt>, etc...

        <li><tt>llvm/include/Support</tt> - This directory contains generic
        support libraries that are independant of LLVM, but are used by LLVM.
        For example, some C++ STL utilities and a Command Line option processing
        library.
     </ol>

     <!------------------------------------------------------------------------->
     <h3><a name="lib"><tt>llvm/lib</tt></a></h3>
     <!------------------------------------------------------------------------->

     This directory contains most source files of LLVM system. In LLVM almost all
     code exists in libraries, making it very easy to share code among the
     different <a href="#tools">tools</a>.<p>

      <dl compact>
       <dt><tt>llvm/lib/VMCore/</tt><dd> This directory holds the core LLVM
       source files that implement core classes like Instruction and BasicBlock.

       <dt><tt>llvm/lib/AsmParser/</tt><dd> This directory holds the source code
       for the LLVM assembly language parser library.

       <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
       converter.

       <dt><tt>llvm/lib/Analysis/</tt><dd> This directory contains a variety of
       different program analyses, such as Dominator Information, Call Graphs,
       Induction Variables, Interval Identification, Natural Loop Identification,
       etc...

       <dt><tt>llvm/lib/Transforms/</tt><dd> This directory contains the source
       code for the LLVM to LLVM program transformations, such as Aggressive Dead
       Code Elimination, Sparse Conditional Constant Propogation, Inlining, Loop
       Invarient Code Motion, Dead Global Elimination, Pool Allocation, and many
       others...

       <dt><tt>llvm/lib/Target/</tt><dd> This directory contains files that
       describe various target architectures for code generation.  For example,
       the llvm/lib/Target/Sparc directory holds the Sparc machine
       description.<br>

       <dt><tt>llvm/lib/CodeGen/</tt><dd> This directory contains the major parts
       of the code generator: Instruction Selector, Instruction Scheduling, and
       Register Allocation.

       <dt><tt>llvm/lib/Reoptimizer/</tt><dd> This directory holds code related
       to the runtime reoptimizer framework that is currently under development.

       <dt><tt>llvm/lib/Support/</tt><dd> This directory contains the source code
       that corresponds to the header files located in
       <tt>llvm/include/Support/</tt>.
     </dl>

     <!------------------------------------------------------------------------->
     <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"><tt>llvm/tools</tt></a></h3>
     <!------------------------------------------------------------------------->

     <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
     always get help for a tool by typing <tt>tool_name --help</tt>.  The
     following is a brief introduction to the most important tools.</p>

     <dl compact>
       <dt><tt><b>as</b></tt><dd>The assembler transforms the human readable
       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
       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
       can directly execute LLVM bytecode (although very slowly...). In addition
       to a simple intepreter, <tt>lli</tt> is also has debugger and tracing
       modes (entered by specifying <tt>-debug</tt> or <tt>-trace</tt> on the
       command line, respectively).<p>

       <dt><tt><b>llc</b></tt><dd> <tt>llc</tt> is the LLVM backend compiler,
       which translates LLVM bytecode to a SPARC assembly file.<p>

       <dt><tt><b>llvmgcc</b></tt><dd> <tt>llvmgcc</tt> is a GCC based C frontend
       that has been retargeted to emit LLVM code as the machine code output.  It
       works just like any other GCC compiler, taking the typical <tt>-c, -S, -E,
       -o</tt> options that are typically used.  The source code for the
       <tt>llvmgcc</tt> tool is currently not included in the LLVM cvs tree
       because it is quite large and not very interesting.<p>

       <ol>
         <dt><tt><b>gccas</b></tt><dd> This took 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,
         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
         disassembled or manipulated just like any other bytecode file).  The
         command line interface to <tt>gccas</tt> is designed to be as close as
         possible to the <b>system</b> <tt>as</tt> utility so that the gcc
         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
         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
         <tt>gccld</tt> is designed to match the system linker, to aid
         interfacing with the GCC frontend.<p>
       </ol>

       <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
       available in LLVM.<p>


       <dt><tt><b>analyze</b></tt><dd> <tt>analyze</tt> is used to run a specific
       analysis on an input LLVM bytecode file and print out the results.  It is
       primarily useful for debugging analyses, or familiarizing yourself with
       what an analysis does.<p>

     </dl>

     <!--=====================================================================-->
     <h2><a name="tutorial">An example using the LLVM tool chain</h2>
     <!--=====================================================================-->

     <ol>
     <li>First, create a simple C file, name it 'hello.c':
        <pre>
    #include &lt;stdio.h&gt;
    int main() {
      printf("hello world\n");
      return 0;
    }
        </pre>

     <li>Next, compile the C file into a LLVM bytecode file:<p>

       <tt>% llvmgcc hello.c -o hello</tt><p>

       This will create two result files: <tt>hello</tt> and
       <tt>hello.bc</tt>. The <tt>hello.bc</tt> is the LLVM bytecode that
       corresponds the the compiled program and the library facilities that it
       required.  <tt>hello</tt> is a simple shell script that runs the bytecode
       file with <tt>lli</tt>, making the result directly executable.<p>

     <li>Run the program. To make sure the program ran, execute one of the
     following commands:<p>

       <tt>% ./hello</tt><p>

       or<p>

       <tt>% lli hello.bc</tt><p>

     <li>Use the <tt>dis</tt> utility to take a look at the LLVM assembly
     code:<p>

       <tt>% dis < hello.bc | less</tt><p>

     <li>Compile the program to native Sparc assembly using the code
     generator:<p>

       <tt>% llc hello.bc -o hello.s</tt><p>

     <li>Assemble the native sparc assemble file into a program:<p>

       <tt>% /opt/SUNWspro/bin/cc -xarch=v9 hello.s -o hello.sparc</tt><p>

     <li>Execute the native sparc program:<p>

       <tt>% ./hello.sparc</tt><p>

     </ol>


     <!--=====================================================================-->
     <h2><a name="links">Links</a></h2>
     <!--=====================================================================-->

     <p>This document is just an <b>introduction</b> to how to use LLVM to do
     some simple things... there are many more interesting and complicated things
     that you can do that aren't documented here (but we'll gladly accept a patch
     if you want to write something up!).  For more information about LLVM, check
     out:</p>

     <ul>
     <li><a href="http://llvm.cs.uiuc.edu/">LLVM homepage</a></li>
     <li><a href="http://tank.cs.uiuc.edu/doxygen/">LLVM doxygen tree</a></li>
     </ul>

     <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>

 	    <!-- Created: Mon Jul  1 02:29:02 CDT 2002 -->
 	    <!-- hhmts start -->
 Last modified: Fri Aug  9 11:13:34 CDT 2002
 <!-- hhmts end -->
   </body>
 </html>
	<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
	<html>
	<head>
	<title>Getting Started with LLVM System</title>
	</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>

	<ul>
	<li><a href="#quickstart">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>
	</ol>
	<li><a href="#layout">Program layout</a>
	<ol>
	<li><a href="#cvsdir">CVS directories</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>



	<!--=====================================================================-->
	<h2><a name="quickstart">Getting Started with LLVM</a></h2>
	<!--=====================================================================-->

	<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="tools">Checkout LLVM from CVS</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><tt>cvs -d /home/vadve/vadve/Research/DynOpt/CVSRepository checkout
	llvm</tt></p>

	<p>This will create an '<tt>llvm</tt>' directory in your home directory and
	fully populate it with the source code for LLVM.</p>


	<!------------------------------------------------------------------------->
	<h3><a name="tools">Set up your environment</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

	# Make the LLVM tools easy to use...
	setenv PATH ~/llvm/tools/Debug:${PATH}
	</pre>

	<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 <tt>llvm/tools/Debug</tt> directory inside of the
	sourcebase. Adding them to your path will make it much easier to use
	them.</p>



	<!------------------------------------------------------------------------->
	<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
	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>

	<p>By default, the LLVM build process sends all temporary (<tt>.o</tt>,
	<tt>.so</tt>, <tt>.a</tt>) files into a <tt>/shared/[your login
	name]/...</tt> directory, which is supposed to be on a disk local to the
	current machine. If you get an error talking about a <tt>/shared</tt>
	directory, and you find out that it doesn't exist, try enabling the
	"<tt>BUILD_ROOT = .</tt> line in the top level <tt>Makefile.common</tt> that
	will change LLVM to build into the current directory instead of
	<tt>/shared</tt>.<p>


	<!--=====================================================================-->
	<h2><a name="layout">Program Layout</a></h2>
	<!--=====================================================================-->

	<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"><tt>CVS</tt> directories</a></h3>
	<!------------------------------------------------------------------------->

	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"><tt>Depend</tt>, <tt>Debug</tt>, & <tt>Release</tt>
	directories</a></h3>
	<!------------------------------------------------------------------------->

	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 <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"><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:<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>,
	<tt>Reoptimizer</tt>, <tt>Target</tt>, <tt>Transforms</tt>, etc...

	<li><tt>llvm/include/Support</tt> - This directory contains generic
	support libraries that are independant of LLVM, but are used by LLVM.
	For example, some C++ STL utilities and a Command Line option processing
	library.
	</ol>

	<!------------------------------------------------------------------------->
	<h3><a name="lib"><tt>llvm/lib</tt></a></h3>
	<!------------------------------------------------------------------------->

	This directory contains most source files of LLVM system. In LLVM almost all
	code exists in libraries, making it very easy to share code among the
	different <a href="#tools">tools</a>.<p>

	<dl compact>
	<dt><tt>llvm/lib/VMCore/</tt><dd> This directory holds the core LLVM
	source files that implement core classes like Instruction and BasicBlock.

	<dt><tt>llvm/lib/AsmParser/</tt><dd> This directory holds the source code
	for the LLVM assembly language parser library.

	<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
	converter.

	<dt><tt>llvm/lib/Analysis/</tt><dd> This directory contains a variety of
	different program analyses, such as Dominator Information, Call Graphs,
	Induction Variables, Interval Identification, Natural Loop Identification,
	etc...

	<dt><tt>llvm/lib/Transforms/</tt><dd> This directory contains the source
	code for the LLVM to LLVM program transformations, such as Aggressive Dead
	Code Elimination, Sparse Conditional Constant Propogation, Inlining, Loop
	Invarient Code Motion, Dead Global Elimination, Pool Allocation, and many
	others...

	<dt><tt>llvm/lib/Target/</tt><dd> This directory contains files that
	describe various target architectures for code generation. For example,
	the llvm/lib/Target/Sparc directory holds the Sparc machine
	description.<br>

	<dt><tt>llvm/lib/CodeGen/</tt><dd> This directory contains the major parts
	of the code generator: Instruction Selector, Instruction Scheduling, and
	Register Allocation.

	<dt><tt>llvm/lib/Reoptimizer/</tt><dd> This directory holds code related
	to the runtime reoptimizer framework that is currently under development.

	<dt><tt>llvm/lib/Support/</tt><dd> This directory contains the source code
	that corresponds to the header files located in
	<tt>llvm/include/Support/</tt>.
	</dl>

	<!------------------------------------------------------------------------->
	<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"><tt>llvm/tools</tt></a></h3>
	<!------------------------------------------------------------------------->

	<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
	always get help for a tool by typing <tt>tool_name --help</tt>. The
	following is a brief introduction to the most important tools.</p>

	<dl compact>
	<dt><tt><b>as</b></tt><dd>The assembler transforms the human readable
	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
	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
	can directly execute LLVM bytecode (although very slowly...). In addition
	to a simple intepreter, <tt>lli</tt> is also has debugger and tracing
	modes (entered by specifying <tt>-debug</tt> or <tt>-trace</tt> on the
	command line, respectively).<p>

	<dt><tt><b>llc</b></tt><dd> <tt>llc</tt> is the LLVM backend compiler,
	which translates LLVM bytecode to a SPARC assembly file.<p>

	<dt><tt><b>llvmgcc</b></tt><dd> <tt>llvmgcc</tt> is a GCC based C frontend
	that has been retargeted to emit LLVM code as the machine code output. It
	works just like any other GCC compiler, taking the typical <tt>-c, -S, -E,
	-o</tt> options that are typically used. The source code for the
	<tt>llvmgcc</tt> tool is currently not included in the LLVM cvs tree
	because it is quite large and not very interesting.<p>

	<ol>
	<dt><tt><b>gccas</b></tt><dd> This took 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,
	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
	disassembled or manipulated just like any other bytecode file). The
	command line interface to <tt>gccas</tt> is designed to be as close as
	possible to the <b>system</b> <tt>as</tt> utility so that the gcc
	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
	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
	<tt>gccld</tt> is designed to match the system linker, to aid
	interfacing with the GCC frontend.<p>
	</ol>

	<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
	available in LLVM.<p>


	<dt><tt><b>analyze</b></tt><dd> <tt>analyze</tt> is used to run a specific
	analysis on an input LLVM bytecode file and print out the results. It is
	primarily useful for debugging analyses, or familiarizing yourself with
	what an analysis does.<p>

	</dl>

	<!--=====================================================================-->
	<h2><a name="tutorial">An example using the LLVM tool chain</h2>
	<!--=====================================================================-->

	<ol>
	<li>First, create a simple C file, name it 'hello.c':
	<pre>
	#include <stdio.h>
	int main() {
	printf("hello world\n");
	return 0;
	}
	</pre>

	<li>Next, compile the C file into a LLVM bytecode file:<p>

	<tt>% llvmgcc hello.c -o hello</tt><p>

	This will create two result files: <tt>hello</tt> and
	<tt>hello.bc</tt>. The <tt>hello.bc</tt> is the LLVM bytecode that
	corresponds the the compiled program and the library facilities that it
	required. <tt>hello</tt> is a simple shell script that runs the bytecode
	file with <tt>lli</tt>, making the result directly executable.<p>

	<li>Run the program. To make sure the program ran, execute one of the
	following commands:<p>

	<tt>% ./hello</tt><p>

	or<p>

	<tt>% lli hello.bc</tt><p>

	<li>Use the <tt>dis</tt> utility to take a look at the LLVM assembly
	code:<p>

	<tt>% dis < hello.bc \| less</tt><p>

	<li>Compile the program to native Sparc assembly using the code
	generator:<p>

	<tt>% llc hello.bc -o hello.s</tt><p>

	<li>Assemble the native sparc assemble file into a program:<p>

	<tt>% /opt/SUNWspro/bin/cc -xarch=v9 hello.s -o hello.sparc</tt><p>

	<li>Execute the native sparc program:<p>

	<tt>% ./hello.sparc</tt><p>

	</ol>


	<!--=====================================================================-->
	<h2><a name="links">Links</a></h2>
	<!--=====================================================================-->

	<p>This document is just an <b>introduction</b> to how to use LLVM to do
	some simple things... there are many more interesting and complicated things
	that you can do that aren't documented here (but we'll gladly accept a patch
	if you want to write something up!). For more information about LLVM, check
	out:</p>

	<ul>
	<li><a href="http://llvm.cs.uiuc.edu/">LLVM homepage</a></li>
	<li><a href="http://tank.cs.uiuc.edu/doxygen/">LLVM doxygen tree</a></li>
	</ul>

	<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>

	<!-- Created: Mon Jul 1 02:29:02 CDT 2002 -->
	<!-- hhmts start -->
	Last modified: Fri Aug 9 11:13:34 CDT 2002
	<!-- hhmts end -->
	</body>
	</html>