docs/GettingStarted.html

   1 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN"
   2                       "http://www.w3.org/TR/html4/strict.dtd">
   3 <html>
   4 <head>
   5   <title>Getting Started with LLVM System</title>
   6   <link rel="stylesheet" href="llvm.css" type="text/css">
   7 </head>
   8 <body>
   9
  10 <div class="doc_title">
  11   Getting Started with the LLVM System
  12 </div>
  13
  14 <ul>
  15   <li><a href="#overview">Overview</a>
  16   <li><a href="#quickstart">Getting Started Quickly (A Summary)</a>
  17   <li><a href="#requirements">Requirements</a>
  18     <ol>
  19       <li><a href="#hardware">Hardware</a>
  20       <li><a href="#software">Software</a>
  21     </ol></li>
  22
  23   <li><a href="#starting">Getting Started with LLVM</a>
  24     <ol>
  25       <li><a href="#terminology">Terminology and Notation</a>
  26       <li><a href="#environment">Setting Up Your Environment</a>
  27       <li><a href="#unpack">Unpacking the LLVM Archives</a>
  28       <li><a href="#checkout">Checkout LLVM from CVS</a>
  29       <li><a href="#installcf">Install the GCC Front End</a>
  30       <li><a href="#config">Local LLVM Configuration</a>
  31       <li><a href="#compile">Compiling the LLVM Suite Source Code</a>
  32       <li><a href="#objfiles">The Location of LLVM Object Files</a>
  33     </ol></li>
  34
  35   <li><a href="#layout">Program layout</a>
  36     <ol>
  37       <li><a href="#cvsdir"><tt>CVS</tt> directories</a>
  38       <li><a href="#include"><tt>llvm/include</tt></a>
  39       <li><a href="#lib"><tt>llvm/lib</tt></a>
  40       <li><a href="#runtime"><tt>llvm/runtime</tt></a>
  41       <li><a href="#test"><tt>llvm/test</tt></a>
  42       <li><a href="#tools"><tt>llvm/tools</tt></a>
  43       <li><a href="#utils"><tt>llvm/utils</tt></a>
  44     </ol></li>
  45
  46   <li><a href="#tutorial">An Example Using the LLVM Tool Chain</a>
  47   <li><a href="#problems">Common Problems</a>
  48   <li><a href="#links">Links</a>
  49 </ul>
  50
  51 <p>By:
  52   <a href="mailto:gshi1@uiuc.edu">Guochun Shi</a>,
  53   <a href="mailto:sabre@nondot.org">Chris Lattner</a>,
  54   <a href="mailto:criswell@uiuc.edu">John Criswell</a>,
  55   <a href="http://misha.brukman.net">Misha Brukman</a>, and
  56   <a href="http://www.cs.uiuc.edu/~vadve">Vikram Adve</a>.</p>
  57
  58
  59 <!-- *********************************************************************** -->
  60 <div class="doc_section">
  61   <a name="overview"><b>Overview</b></a>
  62 </div>
  63 <!-- *********************************************************************** -->
  64
  65 <div class="doc_text">
  66
  67 <p>Welcome to LLVM! In order to get started, you first need to know some
  68 basic information.</p>
  69
  70 <p>First, LLVM comes in two pieces. The first piece is the LLVM suite. This
  71 contains all of the tools, libraries, and header files needed to use the low
  72 level virtual machine.  It contains an assembler, disassembler, bytecode
  73 analyzer, and bytecode optimizer.  It also contains a test suite that can be
  74 used to test the LLVM tools and the GCC front end.</p>
  75
  76 <p>The second piece is the GCC front end.  This component provides a version of
  77 GCC that compiles C and C++ code into LLVM bytecode.  Currently, the GCC front
  78 end is a modified version of GCC 3.4 (we track the GCC 3.4 development).  Once
  79 compiled into LLVM bytecode, a program can be manipulated with the LLVM tools
  80 from the LLVM suite.</p>
  81
  82 </div>
  83
  84 <!-- *********************************************************************** -->
  85 <div class="doc_section">
  86   <a name="quickstart"><b>Getting Started Quickly (A Summary)</b></a>
  87 </div>
  88 <!-- *********************************************************************** -->
  89
  90 <div class="doc_text">
  91
  92 <p>Here's the short story for getting up and running quickly with LLVM:</p>
  93
  94 <ol>
  95   <li>Install the GCC front end:
  96     <ol>
  97       <li><tt>cd <i>where-you-want-the-C-front-end-to-live</i></tt>
  98       <li><tt>gunzip --stdout cfrontend.<i>platform</i>.tar.gz | tar -xvf -</tt>
  99       <li><b>Sparc Only:</b><br>
 100       <tt>cd cfrontend/sparc<br>
 101           ./fixheaders</tt>
 102     </ol></li>
 103
 104   <li>Get the Source Code
 105   <ul>
 106     <li>With the distributed files:
 107     <ol>
 108       <li><tt>cd <i>where-you-want-llvm-to-live</i></tt>
 109       <li><tt>gunzip --stdout llvm.tar.gz | tar -xvf -</tt>
 110       <li><tt>cd llvm</tt>
 111     </ol></li>
 112
 113     <li>With anonymous CVS access:
 114     <ol>
 115       <li><tt>cd <i>where-you-want-llvm-to-live</i></tt></li>
 116       <li><tt>cvs -d
 117           :pserver:anon@llvm-cvs.cs.uiuc.edu:/var/cvs/llvm login</tt></li>
 118       <li>Hit the return key when prompted for the password.
 119       <li><tt>cvs -z3 -d :pserver:anon@llvm-cvs.cs.uiuc.edu:/var/cvs/llvm
 120           co llvm</tt></li>
 121       <li><tt>cd llvm</tt></li>
 122     </ol></li>
 123   </ul></li>
 124
 125   <li>Configure the LLVM Build Environment
 126   <ol>
 127     <li>Change directory to where you want to store the LLVM object
 128         files and run <tt>configure</tt> to configure the Makefiles and
 129         header files for the default platform. Useful options include:
 130       <ul>
 131         <li><tt>--with-llvmgccdir=<i>directory</i></tt>
 132             <p>Specify the full pathname of where the LLVM GCC frontend is
 133             installed.</p></li>
 134         <li><tt>--enable-spec2000=<i>directory</i></tt>
 135             <p>Enable the SPEC2000 benchmarks for testing.  The SPEC2000
 136             benchmarks should be available in
 137             <tt><i>directory</i></tt>.</p></li>
 138       </ul>
 139   </ol></li>
 140
 141   <li>Build the LLVM Suite:
 142   <ol>
 143       <li>Set your LLVM_LIB_SEARCH_PATH environment variable.
 144       <li><tt>gmake -k |& tee gnumake.out
 145       &nbsp;&nbsp;&nbsp;# this is csh or tcsh syntax</tt>
 146   </ol>
 147
 148 </ol>
 149
 150 <p>Consult the <a href="starting">Getting Started with LLVM</a> section for
 151 detailed information on configuring and compiling LLVM.  See <a
 152 href="#environment">Setting Up Your Environment</a> for tips that simplify
 153 working with the GCC front end and LLVM tools.  Go to <a href="#layout">Program
 154 Layout</a> to learn about the layout of the source code tree.</p>
 155
 156 </div>
 157
 158 <!-- *********************************************************************** -->
 159 <div class="doc_section">
 160   <a name="requirements"><b>Requirements</b></a>
 161 </div>
 162 <!-- *********************************************************************** -->
 163
 164 <div class="doc_text">
 165
 166 <p>Before you begin to use the LLVM system, review the requirements given below.
 167 This may save you some trouble by knowing ahead of time what hardware and
 168 software you will need.</p>
 169
 170 </div>
 171
 172 <!-- ======================================================================= -->
 173 <div class="doc_subsection">
 174   <a name="hardware"><b>Hardware</b></a>
 175 </div>
 176
 177 <div class="doc_text">
 178
 179 <p>LLVM is known to work on the following platforms:</p>
 180
 181 <ul>
 182
 183   <li>Linux on x86 (Pentium and above)
 184   <ul>
 185     <li>Approximately 918 MB of Free Disk Space
 186     <ul>
 187       <li>Source code: 28 MB</li>
 188       <li>Object code: 850 MB</li>
 189       <li>GCC front end: 40 MB</li>
 190     </ul></li>
 191   </ul>
 192   </li>
 193
 194   <p></p>
 195
 196   <li>Solaris on SparcV9 (Ultrasparc)
 197   <ul>
 198     <li>Approximately 1.52 GB of Free Disk Space
 199       <ul>
 200         <li>Source code: 28 MB</li>
 201         <li>Object code: 1470 MB</li>
 202         <li>GCC front end: 50 MB</li>
 203       </ul></li>
 204   </ul>
 205   </li>
 206
 207   <p></p>
 208
 209   <li>FreeBSD on x86 (Pentium and above)
 210   <ul>
 211     <li>Approximately 918 MB of Free Disk Space
 212     <ul>
 213       <li>Source code: 28 MB</li>
 214       <li>Object code: 850 MB</li>
 215       <li>GCC front end: 40 MB</li>
 216     </ul></li>
 217   </ul>
 218   </li>
 219
 220   <p></p>
 221
 222   <li>MacOS X on PowerPC
 223   <ul>
 224     <li>No native code generation
 225     <li>Approximately 1.20 GB of Free Disk Space
 226       <ul>
 227         <li>Source code: 28 MB</li>
 228         <li>Object code: 1160 MB</li>
 229         <li>GCC front end: 40 MB</li>
 230       </ul></li>
 231   </ul>
 232
 233   </li>
 234 </ul>
 235
 236 <p>The LLVM suite <i>may</i> compile on other platforms, but it is not
 237 guaranteed to do so.  If compilation is successful, the LLVM utilities should be
 238 able to assemble, disassemble, analyze, and optimize LLVM bytecode.  Code
 239 generation should work as well, although the generated native code may not work
 240 on your platform.</p>
 241
 242 <p>The GCC front end is not very portable at the moment.  If you want to get it
 243 to work on another platform, you can download a copy of the source and try to
 244 compile it on your platform.</p>
 245
 246 </div>
 247
 248 <!-- ======================================================================= -->
 249 <div class="doc_subsection">
 250   <a name="software"><b>Software</b></a>
 251 </div>
 252
 253 <div class="doc_text">
 254
 255 <p>Compiling LLVM requires that you have several software packages
 256 installed:</p>
 257
 258 <ul>
 259   <li><a href="http://gcc.gnu.org">GCC 3.x with C and C++ language
 260   support</a></li>
 261
 262   <li><a href="http://savannah.gnu.org/projects/make">GNU Make</a></li>
 263
 264   <li><a href="http://www.gnu.org/software/flex">Flex</a></li>
 265
 266   <li><a href="http://www.gnu.org/software/bison/bison.html">Bison</a></li>
 267 </ul>
 268
 269 <p>There are some additional tools that you may want to have when working with
 270 LLVM:</p>
 271
 272 <ul>
 273   <li><A href="http://www.gnu.org/software/autoconf">GNU Autoconf</A>
 274   <li><A href="http://savannah.gnu.org/projects/m4">GNU M4</A>
 275
 276       <p>If you want to make changes to the configure scripts, you will need GNU
 277       autoconf (2.57 or higher), and consequently, GNU M4 (version 1.4 or
 278       higher).</p></li>
 279
 280   <li><A href="http://www.codesourcery.com/qm/qmtest">QMTest</A></li>
 281   <li><A href="http://www.python.org">Python</A>
 282
 283       <p>These are needed to use the LLVM test suite.</p></li>
 284
 285 </ul>
 286
 287 <p>The remainder of this guide is meant to get you up and running with
 288 LLVM and to give you some basic information about the LLVM environment.
 289 A <a href="#starting">complete guide to installation</a> is provided in the
 290 next section.</p>
 291
 292 <p>The later sections of this guide describe the <a
 293 href="#layout">general layout</a> of the the LLVM source tree, a <a
 294 href="#tutorial">simple example</a> using the LLVM tool chain, and <a
 295 href="#links">links</a> to find more information about LLVM or to get
 296 help via e-mail.</p>
 297
 298 </div>
 299
 300 <!-- *********************************************************************** -->
 301 <div class="doc_section">
 302   <a name="starting"><b>Getting Started with LLVM</b></a>
 303 </div>
 304 <!-- *********************************************************************** -->
 305
 306 <!-- ======================================================================= -->
 307 <div class="doc_subsection">
 308   <a name="terminology">Terminology and Notation</a>
 309 </div>
 310
 311 <div class="doc_text">
 312
 313 <p>Throughout this manual, the following names are used to denote paths
 314 specific to the local system and working environment.  <i>These are not
 315 environment variables you need to set but just strings used in the rest
 316 of this document below</i>.  In any of the examples below, simply replace
 317 each of these names with the appropriate pathname on your local system.
 318 All these paths are absolute:</p>
 319
 320 <dl compact>
 321     <dt>SRC_ROOT
 322     <dd>
 323     This is the top level directory of the LLVM source tree.
 324     <p>
 325
 326     <dt>OBJ_ROOT
 327     <dd>
 328     This is the top level directory of the LLVM object tree (i.e. the
 329     tree where object files and compiled programs will be placed.  It
 330     can be the same as SRC_ROOT).
 331     <p>
 332
 333     <dt>LLVMGCCDIR
 334     <dd>
 335     This is the where the LLVM GCC Front End is installed.
 336     <p>
 337     For the pre-built GCC front end binaries, the LLVMGCCDIR is
 338     <tt>cfrontend/<i>platform</i>/llvm-gcc</tt>.
 339 </dl>
 340
 341 </div>
 342
 343 <!-- ======================================================================= -->
 344 <div class="doc_subsection">
 345   <a name="environment">Setting Up Your Environment</a>
 346 </div>
 347
 348 <div class="doc_text">
 349
 350 <p>
 351 In order to compile and use LLVM, you will need to set some environment
 352 variables.  There are also some shell aliases which you may find useful.
 353 You can set these on the command line, or better yet, set them in your
 354 <tt>.cshrc</tt> or <tt>.profile</tt>.
 355
 356 <dl compact>
 357     <dt><tt>LLVM_LIB_SEARCH_PATH</tt>=<tt><i>LLVMGCCDIR</i>/bytecode-libs</tt>
 358     <dd>
 359     This environment variable helps the LLVM GCC front end find bytecode
 360     libraries that it will need for compilation.
 361     <p>
 362
 363     <dt>alias llvmgcc <i>LLVMGCCDIR</i><tt>/bin/gcc</tt>
 364     <dt>alias llvmg++ <i>LLVMGCCDIR</i><tt>/bin/g++</tt>
 365     <dd>
 366     This alias allows you to use the LLVM C and C++ front ends without putting
 367     them in your <tt>PATH</tt> or typing in their complete pathnames.
 368 </dl>
 369
 370 </div>
 371
 372 <!-- ======================================================================= -->
 373 <div class="doc_subsection">
 374   <a name="unpack">Unpacking the LLVM Archives</a></h3>
 375 </div>
 376
 377 <div class="doc_text">
 378
 379 <p>
 380 If you have the LLVM distribution, you will need to unpack it before you
 381 can begin to compile it.  LLVM is distributed as a set of two files: the LLVM
 382 suite and the LLVM GCC front end compiled for your platform.  Each
 383 file is a TAR archive that is compressed with the gzip program.
 384 </p>
 385
 386 <p> The files are as follows:
 387 <dl compact>
 388     <dt>llvm-1.1.tar.gz
 389     <dd>This is the source code to the LLVM suite.
 390     <p>
 391
 392     <dt>cfrontend-1.1.sparc-sun-solaris2.8.tar.gz
 393     <dd>This is the binary release of the GCC front end for Solaris/Sparc.
 394     <p>
 395
 396     <dt>cfrontend-1.1.i686-redhat-linux-gnu.tar.gz
 397     <dd>This is the binary release of the GCC front end for Linux/x86.
 398     <p>
 399
 400     <dt>cfrontend-1.1.i386-unknown-freebsd5.1.tar.gz
 401     <dd>This is the binary release of the GCC front end for FreeBSD/x86.
 402     <p>
 403
 404     <dt>cfrontend-1.1.powerpc-apple-darwin7.0.0.tar.gz
 405     <dd>This is the binary release of the GCC front end for MacOS X/PPC.
 406 </dl>
 407
 408 </div>
 409
 410 <!-- ======================================================================= -->
 411 <div class="doc_subsection">
 412   <a name="checkout">Checkout LLVM from CVS</a></h3>
 413 </div>
 414
 415 <div class="doc_text">
 416
 417 <p>If you have access to our CVS repository, you can get a fresh copy of
 418 the entire source code.  All you need to do is check it out from CVS as
 419 follows:</p>
 420
 421 <ul>
 422 <li><tt>cd <i>where-you-want-llvm-to-live</i></tt>
 423   <li><tt>cvs -d :pserver:anon@llvm-cvs.cs.uiuc.edu:/var/cvs/llvm login</tt>
 424   <li>Hit the return key when prompted for the password.
 425   <li><tt>cvs -z3 -d :pserver:anon@llvm-cvs.cs.uiuc.edu:/var/cvs/llvm co
 426       llvm</tt>
 427 </ul>
 428
 429 <p>This will create an '<tt>llvm</tt>' directory in the current
 430 directory and fully populate it with the LLVM source code, Makefiles,
 431 test directories, and local copies of documentation files.</p>
 432
 433 <p>
 434 If you want to get a specific release (as opposed to the most recent revision),
 435 you can specify a label.  The following releases have the following label:
 436 <ul>
 437   <li>
 438   Release 1.1: <b>RELEASE_11</b>
 439   </li>
 440
 441   <li>
 442   Release 1.0: <b>RELEASE_1</b>
 443   </li>
 444 </ul>
 445 </p>
 446
 447 <p>Note that the GCC front end is not included in the CVS repository. You
 448 should have downloaded the binary distribution for your platform.</p>
 449
 450 </div>
 451
 452 <!-- ======================================================================= -->
 453 <div class="doc_subsection">
 454   <a name="installcf">Install the GCC Front End</a></h3>
 455 </div>
 456
 457 <div class="doc_text">
 458
 459 <p>Before configuring and compiling the LLVM suite, you need to extract the LLVM
 460 GCC front end from the binary distribution.  It is used for building the
 461 bytecode libraries later used by the GCC front end for linking programs, and its
 462 location must be specified when the LLVM suite is configured.</p>
 463
 464 <p>To install the GCC front end, do the following:</p>
 465
 466 <ol>
 467   <li><tt>cd <i>where-you-want-the-front-end-to-live</i></tt></li>
 468   <li><tt>gunzip --stdout cfrontend-<i>version</i>.<i>platform</i>.tar.gz | tar -xvf
 469       -</tt></li>
 470 </ol>
 471
 472 <p>If you are using Solaris/Sparc or MacOS X/PPC, you will need to fix the
 473 header files:</p>
 474
 475 <p><tt>cd cfrontend/sparc<br>
 476    ./fixheaders</tt></p>
 477
 478 <p>The binary versions of the GCC front end may not suit all of your needs.  For
 479 example, the binary distribution may include an old version of a system header
 480 file, not "fix" a header file that needs to be fixed for GCC, or it may be
 481 linked with libraries not available on your system.</p>
 482
 483 <p>In cases like these, you may want to try <a
 484 href="CFEBuildInstrs.html">building the GCC front end from source.</a> This is
 485 not for the faint of heart, so be forewarned.</p>
 486
 487 </div>
 488
 489 <!-- ======================================================================= -->
 490 <div class="doc_subsection">
 491   <a name="config">Local LLVM Configuration</a>
 492 </div>
 493
 494 <div class="doc_text">
 495
 496 <p>Once checked out from the CVS repository, the LLVM suite source code must be
 497 configured via the <tt>configure</tt> script.  This script sets variables in
 498 <tt>llvm/Makefile.config</tt> and <tt>llvm/include/Config/config.h</tt>.  It
 499 also populates <i>OBJ_ROOT</i> with the Makefiles needed to begin building
 500 LLVM.</p>
 501
 502 <p>The following environment variables are used by the <tt>configure</tt>
 503 script to configure the build system:</p>
 504
 505 <table border=1>
 506   <tr>
 507    <th>Variable</th>
 508    <th>Purpose</th>
 509   </tr>
 510
 511   <tr>
 512     <td>CC</td>
 513     <td>Tells <tt>configure</tt> which C compiler to use.  By default,
 514         <tt>configure</tt> will look for the first GCC C compiler in
 515         <tt>PATH</tt>.  Use this variable to override
 516         <tt>configure</tt>'s default behavior.</td>
 517   </tr>
 518
 519   <tr>
 520     <td>CXX</td>
 521     <td>Tells <tt>configure</tt> which C++ compiler to use.  By default,
 522        <tt>configure</tt> will look for the first GCC C++ compiler in
 523        <tt>PATH</tt>.  Use this variable to override
 524        <tt>configure</tt>'s default behavior.</td>
 525   </tr>
 526 </table>
 527
 528 <p>The following options can be used to set or enable LLVM specific options:</p>
 529
 530 <dl compact>
 531   <dt><i>--with-llvmgccdir=LLVMGCCDIR</i>
 532   <dd>
 533     Path to the location where the LLVM C front end binaries and
 534     associated libraries were installed.  This must be specified as an
 535     absolute pathname.
 536     <p>
 537   <dt><i>--enable-optimized</i>
 538   <dd>
 539     Enables optimized compilation by default (debugging symbols are removed
 540     and GCC optimization flags are enabled).  The default is to use an
 541     unoptimized build (also known as a debug build).
 542     <p>
 543   <dt><i>--enable-jit</i>
 544   <dd>
 545     Compile the Just In Time (JIT) compiler functionality.  This is not
 546     available
 547     on all platforms.  The default is dependent on platform, so it is best
 548     to explicitly enable it if you want it.
 549     <p>
 550   <dt><i>--enable-spec2000</i>
 551   <dt><i>--enable-spec2000=&lt;<tt>directory</tt>&gt;</i>
 552   <dd>
 553     Enable the use of SPEC2000 when testing LLVM.  This is disabled by default
 554     (unless <tt>configure</tt> finds SPEC2000 installed).  By specifying
 555     <tt>directory</tt>, you can tell configure where to find the SPEC2000
 556     benchmarks.  If <tt>directory</tt> is left unspecified, <tt>configure</tt>
 557     uses the default value
 558     <tt>/home/vadve/shared/benchmarks/speccpu2000/benchspec</tt>.
 559 </dl>
 560
 561 <p>To configure LLVM, follow these steps:</p>
 562
 563 <ol>
 564     <li>Change directory into the object root directory:
 565     <br>
 566     <tt>cd <i>OBJ_ROOT</i></tt>
 567     <p>
 568
 569     <li>Run the <tt>configure</tt> script located in the LLVM source tree:
 570     <br>
 571     <tt><i>SRC_ROOT</i>/configure</tt>
 572     <p>
 573 </ol>
 574
 575 <p>In addition to running <tt>configure</tt>, you must set the
 576 <tt>LLVM_LIB_SEARCH_PATH</tt> environment variable in your startup scripts.
 577 This environment variable is used to locate "system" libraries like
 578 "<tt>-lc</tt>" and "<tt>-lm</tt>" when linking.  This variable should be set to
 579 the absolute path of the <tt>bytecode-libs</tt> subdirectory of the GCC front
 580 end, or <i>LLVMGCCDIR</i>/<tt>bytecode-libs</tt>.  For example, one might set
 581 <tt>LLVM_LIB_SEARCH_PATH</tt> to
 582 <tt>/home/vadve/lattner/local/x86/llvm-gcc/bytecode-libs</tt> for the x86
 583 version of the GCC front end on our research machines.</p>
 584
 585 </div>
 586
 587 <!-- ======================================================================= -->
 588 <div class="doc_subsection">
 589   <a name="compile">Compiling the LLVM Suite Source Code</a>
 590 </div>
 591
 592 <div class="doc_text">
 593
 594 <p>Once you have configured LLVM, you can build it.  There are three types of
 595 builds:</p>
 596
 597 <dl compact>
 598     <dt>Debug Builds
 599     <dd>
 600     These builds are the default when one types <tt>gmake</tt> (unless the
 601     <tt>--enable-optimized</tt> option was used during configuration).  The
 602     build system will compile the tools and libraries with debugging
 603     information.
 604     <p>
 605
 606     <dt>Release (Optimized) Builds
 607     <dd>
 608     These builds are enabled with the <tt>--enable-optimized</tt> option to
 609     <tt>configure</tt> or by specifying <tt>ENABLE_OPTIMIZED=1</tt> on the
 610     <tt>gmake</tt> command line.  For these builds, the build system will
 611     compile the tools and libraries with GCC optimizations enabled and strip
 612     debugging information from the libraries and executables it generates.
 613     <p>
 614
 615     <dt>Profile Builds
 616     <dd>
 617     These builds are for use with profiling.  They compile profiling
 618     information into the code for use with programs like <tt>gprof</tt>.
 619     Profile builds must be started by specifying <tt>ENABLE_PROFILING=1</tt>
 620     on the <tt>gmake</tt> command line.
 621 </dl>
 622
 623 <p>Once you have LLVM configured, you can build it by entering the
 624 <i>OBJ_ROOT</i> directory and issuing the following command:</p>
 625
 626 <p><tt>gmake</tt></p>
 627
 628 <p>If you have multiple processors in your machine, you may wish to use some of
 629 the parallel build options provided by GNU Make.  For example, you could use the
 630 command:</p>
 631
 632 <p><tt>gmake -j2</tt></p>
 633
 634 <p>There are several special targets which are useful when working with the LLVM
 635 source code:</p>
 636
 637 <dl compact>
 638   <dt><tt>gmake clean</tt>
 639   <dd>
 640   Removes all files generated by the build.  This includes object files,
 641   generated C/C++ files, libraries, and executables.
 642   <p>
 643
 644   <dt><tt>gmake distclean</tt>
 645   <dd>
 646   Removes everything that <tt>gmake clean</tt> does, but also removes
 647   files generated by <tt>configure</tt>.  It attempts to return the
 648   source tree to the original state in which it was shipped.
 649   <p>
 650
 651   <dt><tt>gmake install</tt>
 652   <dd>
 653   Installs LLVM files into the proper location.  For the most part,
 654   this does nothing, but it does install bytecode libraries into the
 655   GCC front end's bytecode library directory.  If you need to update
 656   your bytecode libraries, this is the target to use once you've built
 657   them.
 658   <p>
 659 </dl>
 660
 661 <p>It is also possible to override default values from <tt>configure</tt> by
 662 declaring variables on the command line.  The following are some examples:</p>
 663
 664 <dl compact>
 665   <dt><tt>gmake ENABLE_OPTIMIZED=1</tt>
 666   <dd>
 667   Perform a Release (Optimized) build.
 668   <p>
 669
 670   <dt><tt>gmake ENABLE_PROFILING=1</tt>
 671   <dd>
 672   Perform a Profiling build.
 673   <p>
 674
 675   <dt><tt>gmake VERBOSE=1</tt>
 676   <dd>
 677   Print what <tt>gmake</tt> is doing on standard output.
 678   <p>
 679 </dl>
 680
 681 <p>Every directory in the LLVM object tree includes a <tt>Makefile</tt> to build
 682 it and any subdirectories that it contains.  Entering any directory inside the
 683 LLVM object tree and typing <tt>gmake</tt> should rebuild anything in or below
 684 that directory that is out of date.</p>
 685
 686 </div>
 687
 688 <!-- ======================================================================= -->
 689 <div class="doc_subsection">
 690   <a name="objfiles">The Location of LLVM Object Files</a>
 691 </div>
 692
 693 <div class="doc_text">
 694
 695 <p>The LLVM build system is capable of sharing a single LLVM source tree among
 696 several LLVM builds.  Hence, it is possible to build LLVM for several different
 697 platforms or configurations using the same source tree.</p>
 698
 699 <p>This is accomplished in the typical autoconf manner:</p>
 700
 701 <ul>
 702   <li><p>Change directory to where the LLVM object files should live:</p>
 703
 704       <p><tt>cd <i>OBJ_ROOT</i></tt></p></li>
 705
 706   <li><p>Run the <tt>configure</tt> script found in the LLVM source
 707       directory:</p>
 708
 709       <p><tt><i>SRC_ROOT</i>/configure</tt></p></li>
 710 </ul>
 711
 712 <p>The LLVM build will place files underneath <i>OBJ_ROOT</i> in directories
 713 named after the build type:</p>
 714
 715 <dl compact>
 716   <dt>Debug Builds
 717   <dd>
 718   <dl compact>
 719     <dt>Tools
 720     <dd><tt><i>OBJ_ROOT</i>/tools/Debug</tt>
 721     <dt>Libraries
 722     <dd><tt><i>OBJ_ROOT</i>/lib/Debug</tt>
 723   </dl>
 724   <p>
 725
 726   <dt>Release Builds
 727   <dd>
 728   <dl compact>
 729     <dt>Tools
 730     <dd><tt><i>OBJ_ROOT</i>/tools/Release</tt>
 731     <dt>Libraries
 732     <dd><tt><i>OBJ_ROOT</i>/lib/Release</tt>
 733   </dl>
 734   <p>
 735
 736   <dt>Profile Builds
 737   <dd>
 738   <dl compact>
 739     <dt>Tools
 740     <dd><tt><i>OBJ_ROOT</i>/tools/Profile</tt>
 741     <dt>Libraries
 742     <dd><tt><i>OBJ_ROOT</i>/lib/Profile</tt>
 743   </dl>
 744 </dl>
 745
 746 </div>
 747
 748 <!-- *********************************************************************** -->
 749 <div class="doc_section">
 750   <a name="layout"><b>Program Layout</b></a>
 751 </div>
 752 <!-- *********************************************************************** -->
 753
 754 <div class="doc_text">
 755
 756 <p>One useful source of information about the LLVM source base is the LLVM <a
 757 href="http://www.doxygen.org">doxygen</a> documentation, available at <tt><a
 758 href="http://llvm.cs.uiuc.edu/doxygen/">http://llvm.cs.uiuc.edu/doxygen/</a></tt>.
 759 The following is a brief introduction to code layout:</p>
 760
 761 </div>
 762
 763 <!-- ======================================================================= -->
 764 <div class="doc_subsection">
 765   <a name="cvsdir"><tt>CVS</tt> directories</a>
 766 </div>
 767
 768 <div class="doc_text">
 769
 770 <p>Every directory checked out of CVS will contain a <tt>CVS</tt> directory; for
 771 the most part these can just be ignored.</p>
 772
 773 </div>
 774
 775 <!-- ======================================================================= -->
 776 <div class="doc_subsection">
 777   <a name="include"><tt>llvm/include</tt></a>
 778 </div>
 779
 780 <div class="doc_text">
 781
 782 <p>This directory contains public header files exported from the LLVM
 783 library. The three main subdirectories of this directory are:</p>
 784
 785 <ol>
 786   <li><tt>llvm/include/llvm</tt> - This directory contains all of the LLVM
 787       specific header files.  This directory also has subdirectories for
 788       different portions of LLVM: <tt>Analysis</tt>, <tt>CodeGen</tt>,
 789       <tt>Target</tt>, <tt>Transforms</tt>, etc...</li>
 790
 791   <li><tt>llvm/include/Support</tt> - This directory contains generic
 792       support libraries that are independent of LLVM, but are used by LLVM.
 793       For example, some C++ STL utilities and a Command Line option processing
 794       library store their header files here.</li>
 795
 796   <li><tt>llvm/include/Config</tt> - This directory contains header files
 797       configured by the <tt>configure</tt> script.  They wrap "standard" UNIX
 798       and C header files.  Source code can include these header files which
 799       automatically take care of the conditional #includes that the
 800       <tt>configure</tt> script generates.</li>
 801 </ol>
 802
 803 </div>
 804
 805 <!-- ======================================================================= -->
 806 <div class="doc_subsection">
 807   <a name="lib"><tt>llvm/lib</tt></a>
 808 </div>
 809
 810 <div class="doc_text">
 811
 812 <p>This directory contains most of the source files of the LLVM system. In LLVM,
 813 almost all code exists in libraries, making it very easy to share code among the
 814 different <a href="#tools">tools</a>.</p>
 815
 816 <dl compact>
 817   <dt><tt>llvm/lib/VMCore/</tt><dd> This directory holds the core LLVM
 818   source files that implement core classes like Instruction and BasicBlock.
 819
 820   <dt><tt>llvm/lib/AsmParser/</tt><dd> This directory holds the source code
 821   for the LLVM assembly language parser library.
 822
 823   <dt><tt>llvm/lib/ByteCode/</tt><dd> This directory holds code for reading
 824   and write LLVM bytecode.
 825
 826   <dt><tt>llvm/lib/CWriter/</tt><dd> This directory implements the LLVM to C
 827   converter.
 828
 829   <dt><tt>llvm/lib/Analysis/</tt><dd> This directory contains a variety of
 830   different program analyses, such as Dominator Information, Call Graphs,
 831   Induction Variables, Interval Identification, Natural Loop Identification,
 832   etc...
 833
 834   <dt><tt>llvm/lib/Transforms/</tt><dd> This directory contains the source
 835   code for the LLVM to LLVM program transformations, such as Aggressive Dead
 836   Code Elimination, Sparse Conditional Constant Propagation, Inlining, Loop
 837   Invariant Code Motion, Dead Global Elimination, and many others...
 838
 839   <dt><tt>llvm/lib/Target/</tt><dd> This directory contains files that
 840   describe various target architectures for code generation.  For example,
 841   the llvm/lib/Target/Sparc directory holds the Sparc machine
 842   description.<br>
 843
 844   <dt><tt>llvm/lib/CodeGen/</tt><dd> This directory contains the major parts
 845   of the code generator: Instruction Selector, Instruction Scheduling, and
 846   Register Allocation.
 847
 848   <dt><tt>llvm/lib/Support/</tt><dd> This directory contains the source code
 849   that corresponds to the header files located in
 850   <tt>llvm/include/Support/</tt>.
 851 </dl>
 852
 853 </div>
 854
 855 <!-- ======================================================================= -->
 856 <div class="doc_subsection">
 857   <a name="runtime"><tt>llvm/runtime</tt></a>
 858 </div>
 859
 860 <div class="doc_text">
 861
 862 <p>This directory contains libraries which are compiled into LLVM bytecode and
 863 used when linking programs with the GCC front end.  Most of these libraries are
 864 skeleton versions of real libraries; for example, libc is a stripped down
 865 version of glibc.</p>
 866
 867 <p>Unlike the rest of the LLVM suite, this directory needs the LLVM GCC front
 868 end to compile.</p>
 869
 870 </div>
 871
 872 <!-- ======================================================================= -->
 873 <div class="doc_subsection">
 874   <a name="test"><tt>llvm/test</tt></a>
 875 </div>
 876
 877 <div class="doc_text">
 878
 879 <p>This directory contains regression tests and source code that is used to test
 880 the LLVM infrastructure.</p>
 881
 882 </div>
 883
 884 <!-- ======================================================================= -->
 885 <div class="doc_subsection">
 886   <a name="tools"><tt>llvm/tools</tt></a>
 887 </div>
 888
 889 <div class="doc_text">
 890
 891 <p>The <b>tools</b> directory contains the executables built out of the
 892 libraries above, which form the main part of the user interface.  You can
 893 always get help for a tool by typing <tt>tool_name --help</tt>.  The
 894 following is a brief introduction to the most important tools.</p>
 895
 896 <dl compact>
 897   <dt>
 898
 899   <dt><tt><b>analyze</b></tt><dd> <tt>analyze</tt> is used to run a specific
 900   analysis on an input LLVM bytecode file and print out the results.  It is
 901   primarily useful for debugging analyses, or familiarizing yourself with
 902   what an analysis does.<p>
 903
 904   <dt><tt><b>bugpoint</b></tt><dd> <tt>bugpoint</tt> is used to debug
 905   optimization passes or code generation backends by narrowing down the
 906   given test case to the minimum number of passes and/or instructions that
 907   still cause a problem, whether it is a crash or miscompilation. See <a
 908   href="HowToSubmitABug.html">HowToSubmitABug.html</a> for more information
 909   on using <tt>bugpoint</tt>.<p>
 910
 911   <dt><tt><b>llvm-ar</b></tt><dd>The archiver produces an archive containing
 912   the given LLVM bytecode files, optionally with an index for faster
 913   lookup.<p>
 914
 915   <dt><tt><b>llvm-as</b></tt><dd>The assembler transforms the human readable
 916   LLVM assembly to LLVM bytecode.<p>
 917
 918   <dt><tt><b>llvm-dis</b></tt><dd>The disassembler transforms the LLVM
 919   bytecode to human readable LLVM assembly.  Additionally, it can convert
 920   LLVM bytecode to C, which is enabled with the <tt>-c</tt> option.<p>
 921
 922   <dt><tt><b>llvm-link</b></tt><dd> <tt>llvm-link</tt>, not surprisingly,
 923   links multiple LLVM modules into a single program.<p>
 924
 925   <dt><tt><b>lli</b></tt><dd> <tt>lli</tt> is the LLVM interpreter, which
 926   can directly execute LLVM bytecode (although very slowly...). In addition
 927   to a simple interpreter, <tt>lli</tt> also has a tracing mode (entered by
 928   specifying <tt>-trace</tt> on the command line). Finally, for
 929   architectures that support it (currently only x86 and Sparc), by default,
 930   <tt>lli</tt> will function as a Just-In-Time compiler (if the
 931   functionality was compiled in), and will execute the code <i>much</i>
 932   faster than the interpreter.<p>
 933
 934   <dt><tt><b>llc</b></tt><dd> <tt>llc</tt> is the LLVM backend compiler,
 935   which translates LLVM bytecode to a SPARC or x86 assembly file.<p>
 936
 937   <dt><tt><b>llvmgcc</b></tt><dd> <tt>llvmgcc</tt> is a GCC-based C frontend
 938   that has been retargeted to emit LLVM code as the machine code output.  It
 939   works just like any other GCC compiler, taking the typical <tt>-c, -S, -E,
 940   -o</tt> options that are typically used.  The source code for the
 941   <tt>llvmgcc</tt> tool is currently not included in the LLVM CVS tree
 942   because it is quite large and not very interesting.<p>
 943
 944   <ol>
 945     <dt><tt><b>gccas</b></tt><dd> This tool is invoked by the
 946     <tt>llvmgcc</tt> frontend as the "assembler" part of the compiler.  This
 947     tool actually assembles LLVM assembly to LLVM bytecode,
 948     performs a variety of optimizations, and outputs LLVM bytecode.  Thus
 949     when you invoke <tt>llvmgcc -c x.c -o x.o</tt>, you are causing
 950     <tt>gccas</tt> to be run, which writes the <tt>x.o</tt> file (which is
 951     an LLVM bytecode file that can be disassembled or manipulated just like
 952     any other bytecode file).  The command line interface to <tt>gccas</tt>
 953     is designed to be as close as possible to the <b>system</b>
 954     `<tt>as</tt>' utility so that the gcc frontend itself did not have to be
 955     modified to interface to a "weird" assembler.<p>
 956
 957     <dt><tt><b>gccld</b></tt><dd> <tt>gccld</tt> links together several LLVM
 958     bytecode files into one bytecode file and does some optimization.  It is
 959     the linker invoked by the GCC frontend when multiple .o files need to be
 960     linked together.  Like <tt>gccas</tt>, the command line interface of
 961     <tt>gccld</tt> is designed to match the system linker, to aid
 962     interfacing with the GCC frontend.<p>
 963   </ol>
 964
 965   <dt><tt><b>opt</b></tt><dd> <tt>opt</tt> reads LLVM bytecode, applies a
 966   series of LLVM to LLVM transformations (which are specified on the command
 967   line), and then outputs the resultant bytecode.  The '<tt>opt --help</tt>'
 968   command is a good way to get a list of the program transformations
 969   available in LLVM.<p>
 970
 971 </dl>
 972
 973 </div>
 974
 975 <!-- ======================================================================= -->
 976 <div class="doc_subsection">
 977   <a name="utils"><tt>llvm/utils</tt></a>
 978 </div>
 979
 980 <div class="doc_text">
 981
 982 <p>This directory contains utilities for working with LLVM source code, and some
 983 of the utilities are actually required as part of the build process because they
 984 are code generators for parts of LLVM infrastructure.</p>
 985
 986 <dl compact>
 987   <td><tt><b>Burg/</b></tt><dd> <tt>Burg</tt> is an instruction selector
 988   generator -- it builds trees on which it then performs pattern-matching to
 989   select instructions according to the patterns the user has specified. Burg
 990   is currently used in the Sparc V9 backend.<p>
 991
 992   <dt><tt><b>codegen-diff</b></tt><dd> <tt>codegen-diff</tt> is a script
 993   that finds differences between code that LLC generates and code that LLI
 994   generates. This is a useful tool if you are debugging one of them,
 995   assuming that the other generates correct output. For the full user
 996   manual, run <tt>`perldoc codegen-diff'</tt>.<p>
 997
 998   <dt><tt><b>cvsupdate</b></tt><dd> <tt>cvsupdate</tt> is a script that will
 999   update your CVS tree, but produce a much cleaner and more organized output
1000   than simply running <tt>`cvs -z3 up -dP'</tt> will. For example, it will group
1001   together all the new and updated files and modified files in separate
1002   sections, so you can see at a glance what has changed. If you are at the
1003   top of your LLVM CVS tree, running <tt>utils/cvsupdate</tt> is the
1004   preferred way of updating the tree.<p>
1005
1006   <dt><tt><b>emacs/</b></tt><dd> The <tt>emacs</tt> directory contains
1007   syntax-highlighting files which will work with Emacs and XEmacs editors,
1008   providing syntax highlighting support for LLVM assembly files and TableGen
1009   description files. For information on how to use the syntax files, consult
1010   the <tt>README</tt> file in that directory.<p>
1011
1012   <dt><tt><b>getsrcs.sh</b></tt><dd> The <tt>getsrcs.sh</tt> script finds
1013   and outputs all non-generated source files, which is useful if one wishes
1014   to do a lot of development across directories and does not want to
1015   individually find each file. One way to use it is to run, for example:
1016   <tt>xemacs `utils/getsources.sh`</tt> from the top of your LLVM source
1017   tree.<p>
1018
1019   <dt><tt><b>makellvm</b></tt><dd> The <tt>makellvm</tt> script compiles all
1020   files in the current directory and then compiles and links the tool that
1021   is the first argument. For example, assuming you are in the directory
1022   <tt>llvm/lib/Target/Sparc</tt>, if <tt>makellvm</tt> is in your path,
1023   simply running <tt>makellvm llc</tt> will make a build of the current
1024   directory, switch to directory <tt>llvm/tools/llc</tt> and build it,
1025   causing a re-linking of LLC.<p>
1026
1027   <dt><tt><b>NightlyTest.pl</b></tt> and
1028   <tt><b>NightlyTestTemplate.html</b></tt><dd> These files are used in a
1029   cron script to generate nightly status reports of the functionality of
1030   tools, and the results can be seen by following the appropriate link on
1031   the <a href="http://llvm.cs.uiuc.edu/">LLVM homepage</a>.<p>
1032
1033   <dt><tt><b>TableGen/</b></tt><dd> The <tt>TableGen</tt> directory contains
1034   the tool used to generate register descriptions, instruction set
1035   descriptions, and even assemblers from common TableGen description
1036   files.<p>
1037
1038   <dt><tt><b>vim/</b></tt><dd> The <tt>vim</tt> directory contains
1039   syntax-highlighting files which will work with the VIM editor, providing
1040   syntax highlighting support for LLVM assembly files and TableGen
1041   description files. For information on how to use the syntax files, consult
1042   the <tt>README</tt> file in that directory.<p>
1043
1044 </dl>
1045
1046 </div>
1047
1048 <!-- *********************************************************************** -->
1049 <div class="doc_section">
1050   <a name="tutorial">An Example Using the LLVM Tool Chain</a>
1051 </div>
1052 <!-- *********************************************************************** -->
1053
1054 <div class="doc_text">
1055
1056 <ol>
1057   <li>First, create a simple C file, name it 'hello.c':
1058        <pre>
1059    #include &lt;stdio.h&gt;
1060    int main() {
1061      printf("hello world\n");
1062      return 0;
1063    }
1064        </pre></li>
1065
1066   <li><p>Next, compile the C file into a LLVM bytecode file:</p>
1067       <p><tt>% llvmgcc hello.c -o hello</tt></p>
1068
1069       <p>This will create two result files: <tt>hello</tt> and
1070       <tt>hello.bc</tt>. The <tt>hello.bc</tt> is the LLVM bytecode that
1071       corresponds the the compiled program and the library facilities that it
1072       required.  <tt>hello</tt> is a simple shell script that runs the bytecode
1073       file with <tt>lli</tt>, making the result directly executable.</p></li>
1074
1075   <li><p>Run the program. To make sure the program ran, execute one of the
1076       following commands:</p>
1077
1078       <p><tt>% ./hello</tt></p>
1079
1080       <p>or</p>
1081
1082       <p><tt>% lli hello.bc</tt></p></li>
1083
1084   <li><p>Use the <tt>llvm-dis</tt> utility to take a look at the LLVM assembly
1085       code:</p>
1086
1087       <p><tt>% llvm-dis &lt; hello.bc | less</tt><p></li>
1088
1089   <li><p>Compile the program to native Sparc assembly using the code
1090       generator (assuming you are currently on a Sparc system):</p>
1091
1092       <p><tt>% llc hello.bc -o hello.s</tt></p>
1093
1094   <li><p>Assemble the native sparc assemble file into a program:</p>
1095
1096       <p><tt>% /opt/SUNWspro/bin/cc -xarch=v9 hello.s -o hello.sparc</tt></p>
1097
1098   <li><p>Execute the native sparc program:</p>
1099
1100       <p><tt>% ./hello.sparc</tt></p></li>
1101
1102 </ol>
1103
1104 </div>
1105
1106 <!-- *********************************************************************** -->
1107 <div class="doc_section">
1108   <a name="problems">Common Problems</a>
1109 </div>
1110 <!-- *********************************************************************** -->
1111
1112 <div class="doc_text">
1113
1114 <p>If you are having problems building or using LLVM, or if you have any other
1115 general questions about LLVM, please consult the <a href="FAQ.html">Frequently
1116 Asked Questions</a> page.</p>
1117
1118 </div>
1119
1120 <!-- *********************************************************************** -->
1121 <div class="doc_section">
1122   <a name="links">Links</a>
1123 </div>
1124 <!-- *********************************************************************** -->
1125
1126 <div class="doc_text">
1127
1128 <p>This document is just an <b>introduction</b> to how to use LLVM to do
1129 some simple things... there are many more interesting and complicated things
1130 that you can do that aren't documented here (but we'll gladly accept a patch
1131 if you want to write something up!).  For more information about LLVM, check
1132 out:</p>
1133
1134 <ul>
1135   <li><a href="http://llvm.cs.uiuc.edu/">LLVM homepage</a></li>
1136   <li><a href="http://llvm.cs.uiuc.edu/doxygen/">LLVM doxygen tree</a></li>
1137   <li><a href="http://llvm.cs.uiuc.edu/docs/Projects.html">Starting a Project
1138   that Uses LLVM</a></li>
1139 </ul>
1140
1141 </div>
1142
1143 <!-- *********************************************************************** -->
1144
1145 <hr>
1146 <address>
1147   <a href="mailto:sabre@nondot.org">Chris Lattner</a><br>
1148   <a href="http://llvm.cs.uiuc.edu">The LLVM Compiler Infrastructure</a><br>
1149   Last modified: $Date$
1150 </address>
1151
1152 </body>
1153 </html>