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