docs/GettingStarted.html

   1 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN">
   2 <html>
   3   <head>
   4     <title>Getting Started with LLVM System</title>
   5   </head>
   6
   7   <body bgcolor=white>
   8     <h1>Getting Started with the LLVM System<br><font size=3>By: <a
   9     href="mailto:gshi1@uiuc.edu">Guochun Shi</a> and <a
  10     href="mailto:sabre@nondot.org">Chris Lattner</a></font></h1>
  11
  12     <ul>
  13       <li><a href="#quickstart">Getting started with LLVM</a>
  14         <ol>
  15           <li><a href="#cvs">Checkout LLVM from CVS</a>
  16           <li><a href="#shared">Access to <tt>/shared</tt></a>
  17           <li><a href="#environment">Set up your environment</a>
  18           <li><a href="#compile">Compiling the Source Code</a>
  19         </ol>
  20       <li><a href="#layout">Program layout</a>
  21         <ol>
  22           <li><a href="#cvsdir">CVS directories</a>
  23           <li><a href="#dd"><tt>Depend</tt>, <tt>Debug</tt>, &amp;
  24                <tt>Release</tt> directories</a></li>
  25           <li><a href="#include"><tt>llvm/include</tt></a>
  26           <li><a href="#lib"><tt>llvm/lib</tt></a>
  27           <li><a href="#test"><tt>llvm/test</tt></a>
  28           <li><a href="#tools"><tt>llvm/tools</tt></a>
  29         </ol>
  30       <li><a href="#tutorial">An example using the LLVM tool chain</a>
  31       <li><a href="#links">Links</a>
  32     </ul>
  33
  34
  35
  36     <!--=====================================================================-->
  37     <h2><a name="quickstart">Getting Started with LLVM</a></h2>
  38     <!--=====================================================================-->
  39
  40     <p>This guide is meant to get you up and running with LLVM as quickly as
  41     possible.  Once you get the basic system running you can choose an area to
  42     dive into and learn more about.  If you get stuck or something is missing
  43     from this document, please email <a
  44     href="mailto:sabre@nondot.org">Chris</a>.</p>
  45
  46
  47     <!------------------------------------------------------------------------->
  48     <h3><a name="tools">Checkout LLVM from CVS</a></h3>
  49     <!------------------------------------------------------------------------->
  50
  51     <p>First step is to get the actual source code.  To do this, all you need to
  52     do is check it out from CVS.  From your home directory, just enter:</p>
  53
  54     <p><tt>cvs -d /home/vadve/vadve/Research/DynOpt/CVSRepository checkout
  55     llvm</tt></p>
  56
  57     <p>This will create an '<tt>llvm</tt>' directory in your home directory and
  58     fully populate it with the source code for LLVM.</p>
  59
  60
  61     <!------------------------------------------------------------------------->
  62     <h3><a name="shared">Access to <tt>/shared</tt></a></h3>
  63     <!------------------------------------------------------------------------->
  64
  65     By default, LLVM is configured to send all compiled files into the
  66     <tt>/shared/[yourloginname]/</tt> directory.  The idea is that this
  67     directory is local to the machine you're working on, so the huge libraries
  68     and <tt>.o</tt> files you will be compiling will not have to be sent over
  69     NFS.  If you are in a situation where this setup is correct, you don't have
  70     to do anything.  If you don't have a <tt>/shared</tt> directory, you will
  71     have to make a couple of modifications to your setup.<p>
  72
  73     The first modification is that you need to enable the "<tt>BUILD_ROOT =
  74     .</tt> line in the top level <tt>Makefile.common</tt>.  This will instruct
  75     LLVM to build into the current directory tree instead of
  76     <tt>/shared</tt>.<p>
  77
  78
  79     <!------------------------------------------------------------------------->
  80     <h3><a name="tools">Set up your environment</a></h3>
  81     <!------------------------------------------------------------------------->
  82
  83     <p>Now that you have the source code available, you should set up your
  84     environment to be able to use the LLVM tools (once compiled) with as little
  85     hassle as possible.  To do this, we recommend that you add the following
  86     lines to your <tt>.cshrc</tt> (or the corresponding lines to your
  87     <tt>.profile</tt> if you use a bourne shell derivative):
  88
  89     <pre>
  90        # Make the C frontend easy to use...
  91        alias llvmgcc /home/vadve/lattner/cvs/gcc_install/bin/gcc
  92
  93        # Make the LLVM tools easy to use...
  94        setenv PATH /shared/[yourloginname]/llvm/tools/Debug:${PATH}
  95     </pre>
  96
  97     <p>The C compiler is not included in the CVS tree you just checked out, so
  98     we just point to the cannonical location, and access it with the
  99     <tt>llvmgcc</tt> command.  The rest of the <a href="#tools">LLVM tools</a>
 100     will be built into the <tt>llvm/tools/Debug</tt> directory.  If you do not
 101     have access to <tt>/shared</tt>, use this line instead:</p>
 102
 103     <pre>
 104        setenv PATH ~/llvm/tools/Debug:${PATH}
 105     </pre>
 106
 107     Adding these two lines to your path will make it much easier to use the LLVM
 108     tools.</p>
 109
 110
 111     <!------------------------------------------------------------------------->
 112     <h3><a name="compile">Compiling the Source Code</a></h3>
 113     <!------------------------------------------------------------------------->
 114
 115     <p>Every directory in the LLVM source tree includes a Makefile to build it,
 116     and any subdirectories that it contains.  These makefiles require that you
 117     use <tt>gmake</tt>, instead of <tt>make</tt> to build them, but can
 118     otherwise be used freely.  To build the entire LLVM system, just enter the
 119     top level <tt>llvm</tt> directory and type <tt>gmake</tt>.  A few minutes
 120     later you will hopefully have a freshly compiled toolchain waiting for you
 121     in <tt>llvm/tools/Debug</tt>.  If you want to look at the libraries that
 122     were compiled, look in <tt>llvm/lib/Debug</tt>.</p>
 123
 124     <p>By default, the LLVM build process sends all temporary (<tt>.o</tt>,
 125     <tt>.so</tt>, <tt>.a</tt>) files into a <tt>/shared/[your login
 126     name]/...</tt> directory, which is supposed to be on a disk local to the
 127     current machine.  If you get an error talking about a <tt>/shared</tt>
 128     directory, follow the instructions in the <a href="#shared">section about
 129     <tt>/shared</tt></a>.<p>
 130
 131
 132
 133     <!--=====================================================================-->
 134     <h2><a name="layout">Program Layout</a></h2>
 135     <!--=====================================================================-->
 136
 137     <p>One useful source of infomation about the LLVM sourcebase is the LLVM <a
 138     href="http://www.doxygen.org">doxygen</a> documentation, available at <tt><a
 139     href="http://llvm.cs.uiuc.edu/doxygen/">http://llvm.cs.uiuc.edu/doxygen/</a></tt>. The
 140     following is a brief introduction to code layout:</p>
 141
 142
 143     <!------------------------------------------------------------------------->
 144     <h3><a name="cvsdir"><tt>CVS</tt> directories</a></h3>
 145     <!------------------------------------------------------------------------->
 146
 147     Every directory checked out of CVS will contain a <tt>CVS</tt> directory,
 148     for the most part these can just be ignored.
 149
 150
 151     <!------------------------------------------------------------------------->
 152     <h3><a name="ddr"><tt>Depend</tt>, <tt>Debug</tt>, &amp; <tt>Release</tt>
 153     directories</a></h3>
 154     <!------------------------------------------------------------------------->
 155
 156     If you are building with the "<tt>BUILD_ROOT=.</tt>" option enabled in the
 157     <tt>Makefile.common</tt> file, most source directories will contain two
 158     directories, <tt>Depend</tt> and <tt>Debug</tt>. The <tt>Depend</tt>
 159     directory contains automatically generated dependance files which are used
 160     during compilation to make sure that source files get rebuilt if a header
 161     file they use is modified. The <tt>Debug</tt> directory holds the object
 162     files, library files and executables that are used for building a debug
 163     enabled build.  The <tt>Release</tt> directory is created to hold the same
 164     files when the <tt>ENABLE_OPTIMIZED=1</tt> flag is passed to <tt>gmake</tt>,
 165     causing an optimized built to be performed.<p>
 166
 167
 168     <!------------------------------------------------------------------------->
 169     <h3><a name="include"><tt>llvm/include</tt></a></h3>
 170     <!------------------------------------------------------------------------->
 171
 172     This directory contains public header files exported from the LLVM
 173     library. The two main subdirectories of this directory are:<p>
 174
 175     <ol>
 176        <li><tt>llvm/include/llvm</tt> - This directory contains all of the LLVM
 177        specific header files.  This directory also has subdirectories for
 178        different portions of llvm: <tt>Analysis</tt>, <tt>CodeGen</tt>,
 179        <tt>Reoptimizer</tt>, <tt>Target</tt>, <tt>Transforms</tt>, etc...
 180
 181        <li><tt>llvm/include/Support</tt> - This directory contains generic
 182        support libraries that are independant of LLVM, but are used by LLVM.
 183        For example, some C++ STL utilities and a Command Line option processing
 184        library.
 185     </ol>
 186
 187     <!------------------------------------------------------------------------->
 188     <h3><a name="lib"><tt>llvm/lib</tt></a></h3>
 189     <!------------------------------------------------------------------------->
 190
 191     This directory contains most source files of LLVM system. In LLVM almost all
 192     code exists in libraries, making it very easy to share code among the
 193     different <a href="#tools">tools</a>.<p>
 194
 195      <dl compact>
 196       <dt><tt>llvm/lib/VMCore/</tt><dd> This directory holds the core LLVM
 197       source files that implement core classes like Instruction and BasicBlock.
 198
 199       <dt><tt>llvm/lib/AsmParser/</tt><dd> This directory holds the source code
 200       for the LLVM assembly language parser library.
 201
 202       <dt><tt>llvm/lib/ByteCode/</tt><dd> This directory holds code for reading
 203       and write LLVM bytecode.
 204
 205       <dt><tt>llvm/lib/CWrite/</tt><dd> This directory implements the LLVM to C
 206       converter.
 207
 208       <dt><tt>llvm/lib/Analysis/</tt><dd> This directory contains a variety of
 209       different program analyses, such as Dominator Information, Call Graphs,
 210       Induction Variables, Interval Identification, Natural Loop Identification,
 211       etc...
 212
 213       <dt><tt>llvm/lib/Transforms/</tt><dd> This directory contains the source
 214       code for the LLVM to LLVM program transformations, such as Aggressive Dead
 215       Code Elimination, Sparse Conditional Constant Propogation, Inlining, Loop
 216       Invarient Code Motion, Dead Global Elimination, Pool Allocation, and many
 217       others...
 218
 219       <dt><tt>llvm/lib/Target/</tt><dd> This directory contains files that
 220       describe various target architectures for code generation.  For example,
 221       the llvm/lib/Target/Sparc directory holds the Sparc machine
 222       description.<br>
 223
 224       <dt><tt>llvm/lib/CodeGen/</tt><dd> This directory contains the major parts
 225       of the code generator: Instruction Selector, Instruction Scheduling, and
 226       Register Allocation.
 227
 228       <dt><tt>llvm/lib/Reoptimizer/</tt><dd> This directory holds code related
 229       to the runtime reoptimizer framework that is currently under development.
 230
 231       <dt><tt>llvm/lib/Support/</tt><dd> This directory contains the source code
 232       that corresponds to the header files located in
 233       <tt>llvm/include/Support/</tt>.
 234     </dl>
 235
 236     <!------------------------------------------------------------------------->
 237     <h3><a name="test"><tt>llvm/test</tt></a></h3>
 238     <!------------------------------------------------------------------------->
 239
 240     <p>This directory contains regression tests and source code that is used to
 241     test the LLVM infrastructure...</p>
 242
 243     <!------------------------------------------------------------------------->
 244     <h3><a name="tools"><tt>llvm/tools</tt></a></h3>
 245     <!------------------------------------------------------------------------->
 246
 247     <p>The <b>tools</b> directory contains the executables built out of the
 248     libraries above, which form the main part of the user interface.  You can
 249     always get help for a tool by typing <tt>tool_name --help</tt>.  The
 250     following is a brief introduction to the most important tools.</p>
 251
 252     <dl compact>
 253       <dt><tt><b>as</b></tt><dd>The assembler transforms the human readable
 254       llvm assembly to llvm bytecode.<p>
 255
 256       <dt><tt><b>dis</b></tt><dd>The disassembler transforms the llvm bytecode
 257       to human readable llvm assembly.  Additionally it can convert LLVM
 258       bytecode to C, which is enabled with the <tt>-c</tt> option.<p>
 259
 260       <dt><tt><b>lli</b></tt><dd> <tt>lli</tt> is the LLVM interpreter, which
 261       can directly execute LLVM bytecode (although very slowly...). In addition
 262       to a simple intepreter, <tt>lli</tt> is also has debugger and tracing
 263       modes (entered by specifying <tt>-debug</tt> or <tt>-trace</tt> on the
 264       command line, respectively).<p>
 265
 266       <dt><tt><b>llc</b></tt><dd> <tt>llc</tt> is the LLVM backend compiler,
 267       which translates LLVM bytecode to a SPARC assembly file.<p>
 268
 269       <dt><tt><b>llvmgcc</b></tt><dd> <tt>llvmgcc</tt> is a GCC based C frontend
 270       that has been retargeted to emit LLVM code as the machine code output.  It
 271       works just like any other GCC compiler, taking the typical <tt>-c, -S, -E,
 272       -o</tt> options that are typically used.  The source code for the
 273       <tt>llvmgcc</tt> tool is currently not included in the LLVM cvs tree
 274       because it is quite large and not very interesting.<p>
 275
 276       <ol>
 277         <dt><tt><b>gccas</b></tt><dd> This took is invoked by the
 278         <tt>llvmgcc</tt> frontend as the "assembler" part of the compiler.  This
 279         tool actually assembles its input, performs a variety of optimizations,
 280         and outputs LLVM bytecode.  Thus when you invoke <tt>llvmgcc -c x.c -o
 281         x.o</tt>, you are causing <tt>gccas</tt> to be run, which writes the
 282         <tt>x.o</tt> file (which is an LLVM bytecode file that can be
 283         disassembled or manipulated just like any other bytecode file).  The
 284         command line interface to <tt>gccas</tt> is designed to be as close as
 285         possible to the <b>system</b> <tt>as</tt> utility so that the gcc
 286         frontend itself did not have to be modified to interface to a "wierd"
 287         assembler.<p>
 288
 289         <dt><tt><b>gccld</b></tt><dd> <tt>gccld</tt> links together several llvm
 290         bytecode files into one bytecode file and does some optimization.  It is
 291         the linker invoked by the gcc frontend when multiple .o files need to be
 292         linked together.  Like <tt>gccas</tt> the command line interface of
 293         <tt>gccld</tt> is designed to match the system linker, to aid
 294         interfacing with the GCC frontend.<p>
 295       </ol>
 296
 297       <dt><tt><b>opt</b></tt><dd> <tt>opt</tt> reads llvm bytecode, applies a
 298       series of LLVM to LLVM transformations (which are specified on the command
 299       line), and then outputs the resultant bytecode.  The '<tt>opt --help</tt>'
 300       command is a good way to get a list of the program transformations
 301       available in LLVM.<p>
 302
 303
 304       <dt><tt><b>analyze</b></tt><dd> <tt>analyze</tt> is used to run a specific
 305       analysis on an input LLVM bytecode file and print out the results.  It is
 306       primarily useful for debugging analyses, or familiarizing yourself with
 307       what an analysis does.<p>
 308
 309     </dl>
 310
 311     <!--=====================================================================-->
 312     <h2><a name="tutorial">An example using the LLVM tool chain</h2>
 313     <!--=====================================================================-->
 314
 315     <ol>
 316     <li>First, create a simple C file, name it 'hello.c':
 317        <pre>
 318    #include &lt;stdio.h&gt;
 319    int main() {
 320      printf("hello world\n");
 321      return 0;
 322    }
 323        </pre>
 324
 325     <li>Next, compile the C file into a LLVM bytecode file:<p>
 326
 327       <tt>% llvmgcc hello.c -o hello</tt><p>
 328
 329       This will create two result files: <tt>hello</tt> and
 330       <tt>hello.bc</tt>. The <tt>hello.bc</tt> is the LLVM bytecode that
 331       corresponds the the compiled program and the library facilities that it
 332       required.  <tt>hello</tt> is a simple shell script that runs the bytecode
 333       file with <tt>lli</tt>, making the result directly executable.<p>
 334
 335     <li>Run the program. To make sure the program ran, execute one of the
 336     following commands:<p>
 337
 338       <tt>% ./hello</tt><p>
 339
 340       or<p>
 341
 342       <tt>% lli hello.bc</tt><p>
 343
 344     <li>Use the <tt>dis</tt> utility to take a look at the LLVM assembly
 345     code:<p>
 346
 347       <tt>% dis < hello.bc | less</tt><p>
 348
 349     <li>Compile the program to native Sparc assembly using the code
 350     generator:<p>
 351
 352       <tt>% llc hello.bc -o hello.s</tt><p>
 353
 354     <li>Assemble the native sparc assemble file into a program:<p>
 355
 356       <tt>% /opt/SUNWspro/bin/cc -xarch=v9 hello.s -o hello.sparc</tt><p>
 357
 358     <li>Execute the native sparc program:<p>
 359
 360       <tt>% ./hello.sparc</tt><p>
 361
 362     </ol>
 363
 364
 365     <!--=====================================================================-->
 366     <h2><a name="links">Links</a></h2>
 367     <!--=====================================================================-->
 368
 369     <p>This document is just an <b>introduction</b> to how to use LLVM to do
 370     some simple things... there are many more interesting and complicated things
 371     that you can do that aren't documented here (but we'll gladly accept a patch
 372     if you want to write something up!).  For more information about LLVM, check
 373     out:</p>
 374
 375     <ul>
 376     <li><a href="http://llvm.cs.uiuc.edu/">LLVM homepage</a></li>
 377     <li><a href="http://tank.cs.uiuc.edu/doxygen/">LLVM doxygen tree</a></li>
 378     </ul>
 379
 380     <hr>
 381
 382     If you have any questions or run into any snags (or you have any
 383     additions...), please send an email to <a
 384     href="mailto:sabre@nondot.org">Chris Lattner</a> or <a
 385     href="mailto:gshi1@uiuc.edu">Guochun Shi</a>. <p>
 386
 387             <!-- Created: Mon Jul  1 02:29:02 CDT 2002 -->
 388             <!-- hhmts start -->
 389 Last modified: Tue Aug 13 16:09:25 CDT 2002
 390 <!-- hhmts end -->
 391   </body>
 392 </html>