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>, and
  12     <a href="http://www.cs.uiuc.edu/~vadve">Vikram Adve</a>
  13     </font></h1></center>
  14
  15     <!--=====================================================================-->
  16     <h2><a name="Contents">Contents</a></h2>
  17     <!--=====================================================================-->
  18
  19     <ul>
  20       <li><a href="#overview">Overview</a>
  21       <ol>
  22           <li><a href="#requirements">Requirements</a>
  23           <ol>
  24               <li><a href="#hardware">Hardware</a>
  25               <li><a href="#software">Software</a>
  26           </ol>
  27       </ol>
  28       <li><a href="#starting">Getting started with LLVM</a>
  29         <ol>
  30           <li><a href="#quickstart">Getting started quickly (a summary)</a>
  31           <li><a href="#terminology">Terminology and Notation</tt></a>
  32           <li><a href="#environment">Setting up your environment</a>
  33           <li><a href="#checkout">Checkout LLVM from CVS</a>
  34           <li><a href="#config">Local LLVM Configuration</tt></a>
  35           <li><a href="#compile">Compiling the LLVM Suite Source Code</a>
  36           <li><a href="#build">Building the LLVM C Front End</a>
  37           <li><a href="#objfiles">The location for object files</tt></a>
  38         </ol>
  39       <li><a href="#layout">Program layout</a>
  40         <ol>
  41           <li><a href="#cvsdir">CVS directories</a>
  42           <li><a href="#include"><tt>llvm/include</tt></a>
  43           <li><a href="#lib"><tt>llvm/lib</tt></a>
  44           <li><a href="#test"><tt>llvm/test</tt></a>
  45           <li><a href="#tools"><tt>llvm/tools</tt></a>
  46         </ol>
  47       <li><a href="#tutorial">An example using the LLVM tool chain</a>
  48       <li><a href="#links">Links</a>
  49     </ul>
  50
  51
  52     <!--=====================================================================-->
  53     <center>
  54     <h2><a name="overview"><b>Overview</b></a></h2>
  55     </center>
  56     <!--=====================================================================-->
  57
  58     Welcome to LLVM!  In order to get started, you first need to know some
  59     basic information.
  60
  61     <p>
  62     First, LLVM comes in two pieces.  The first piece is the LLVM suite.  This
  63     contains all of the tools, libraries, and header files needed to use the
  64     low level virtual machine.  It also contains a test suite that can be used
  65     to test the LLVM tools and the GCC front end.
  66     <p>
  67     The second piece is the GCC front end.  This component provides a version
  68     of GCC that compiles C code into LLVM bytecode.  Currently, the C front end
  69     is a modified version of GCC 3.4 (we track the GCC 3.4 development).
  70     Once compiled into LLVM bytecode, a program can be manipulated with the
  71     LLVM tools.
  72
  73     <!--=====================================================================-->
  74     <h3><a name="requirements"><b>Requirements</b></a></h3>
  75     <!--=====================================================================-->
  76
  77     Before you begin to use the LLVM system, review the requirements given
  78     below.  This may save you some trouble by knowing ahead of time what
  79     hardware and software you will need.
  80
  81     <!--=====================================================================-->
  82     <h4><a name="hardware"><b>Hardware</b></a></h4>
  83     <!--=====================================================================-->
  84     LLVM is known to work on the following platforms:
  85     <ul>
  86         <li> Linux on x86
  87         <ul>
  88             <li> Approximately 700 MB of Free Disk Space
  89             <ul>
  90                 <li>Source code: 30 MB
  91                 <li>Object code: 670 MB
  92             </ul>
  93         </ul>
  94         <li> Solaris on SparcV9 (Ultrasparc)
  95         <ul>
  96             <li> Approximately 1.03 GB of Free Disk Space
  97             <ul>
  98                 <li>Source code: 30 MB
  99                 <li>Object code: 1000 MB
 100             </ul>
 101         </ul>
 102     </ul>
 103
 104     LLVM <i>may</i> compile on other platforms.  The LLVM utilities should work
 105     on other platforms, so it should be possible to generate and produce LLVM
 106     bytecode on unsupported platforms (although bytecode generated on one
 107     platform may not work on another platform).  However, the code generators
 108     and Just-In-Time (JIT) compilers only generate SparcV9 or x86 machine code.
 109
 110     <!--=====================================================================-->
 111     <h4><a name="software"><b>Software</b></a></h4>
 112     <!--=====================================================================-->
 113     <p>
 114     Compiling LLVM requires that you have several different software packages
 115     installed:
 116
 117     <dl compact>
 118         <dt> GCC
 119         <dd>
 120         The GNU Compiler Collection must be installed with C and C++ language
 121         support.  GCC 3.2.x works, and GCC 3.x is generally supported.
 122
 123         <p>
 124         Note that we currently do not support any other C++ compiler.
 125         </p>
 126
 127         <dt> GNU Make
 128         <dd>
 129         The LLVM build system relies upon GNU Make extensions.  Therefore, you
 130         will need GNU Make (sometimes known as gmake) to build LLVM.
 131         <p>
 132
 133         <dt> Flex and Bison
 134         <dd>
 135         The LLVM source code is built using flex and bison.  You will not be
 136         able to configure and compile LLVM without them.
 137         <p>
 138
 139         <dt> GNU M4
 140         <dd>
 141         If you are installing Bison on your machine for the first time, you
 142         will need GNU M4 (version 1.4 or higher).
 143     </dl>
 144
 145     <p>
 146     There are some additional tools that you may want to have when working with
 147     LLVM:
 148     </p>
 149
 150     <ul>
 151         <li>GNU Autoconf
 152         <li>GNU M4
 153         <p>
 154         If you want to make changes to the configure scripts, you will need
 155         GNU autoconf (2.53 or higher), and consequently, GNU M4 (version 1.4
 156         or higher).
 157         </p>
 158     </ul>
 159
 160
 161     <p>The <a href="starting">next section</a> of this guide is meant to get
 162     you up and running with LLVM and to give you some basic information about
 163     the LLVM environment.  The <a href"#quickstart">first subsection</a> gives
 164     a short summary for those who are already familiar with the system and
 165     want to get started as quickly as possible.
 166
 167     <p>The later sections of this guide describe the <a
 168     href="#layout">general layout</a> of the the LLVM source-tree, a <a
 169     href="#tutorial">simple example</a> using the LLVM tool chain, and <a
 170     href="#links">links</a> to find more information about LLVM or to get
 171     help via e-mail.
 172
 173     <!--=====================================================================-->
 174     <center>
 175     <h2><a name="starting"><b>Getting Started</b></a></h2>
 176     </center>
 177     <!--=====================================================================-->
 178
 179     <!--=====================================================================-->
 180     <h3><a name="quickstart"><b>Getting Started Quickly (A Summary)</b></a></h3>
 181     <!--=====================================================================-->
 182
 183     Here's the short story for getting up and running quickly with LLVM:
 184     <ol>
 185     <li>Build the LLVM suite
 186         <ol>
 187         <li>Find the path to the CVS repository containing LLVM (we'll call this <i>CVSROOTDIR</i>).
 188         <li><tt>cd <i>where-you-want-llvm-to-live</i></tt>
 189         <li><tt>cvs -d <i>CVSROOTDIR</i> checkout llvm</tt>
 190         <li><tt>cd llvm</tt>
 191         <li>Run <tt>configure</tt> to configure the Makefiles and header files.
 192         Useful options include:
 193             <ul>
 194                 <li><tt>--with-objroot=<i>directory</i></tt>
 195                 <br>
 196                 Specify where object files should be placed during the build.
 197
 198                 <li><tt>--with-llvmgccdir=<i>directory</i></tt>
 199                 <br>
 200                 Specify where the LLVM C frontend is going to be installed.
 201             </ul>
 202         <li>Set your LLVM_LIB_SEARCH_PATH environment variable.
 203         <li><tt>gmake -k |& tee gnumake.out
 204             &nbsp;&nbsp;&nbsp;# this is csh or tcsh syntax</tt>
 205         </ol>
 206         <p>
 207     <li>Build the LLVM C Front End <b>(optional)</b>
 208         <ol>
 209             <li>Create a directory for the object files to live.
 210             <li><tt>cd <i>object file directory</i></tt>
 211             <li>Run <tt><i>Pathname-to-where-the-source-code-lives</i>/configure --prefix=<i>LLVMGCCDIR</i></tt> to configure GCC.
 212             <li><tt>make bootstrap</tt>
 213             <li><tt>make install</tt>
 214         </ol>
 215     </ol>
 216
 217     <p>See <a href="#environment">Setting up your environment</a> on tips to
 218     simplify working with the LLVM front-end and compiled tools.  See the
 219     other sub-sections below for other useful details in working with LLVM,
 220     or go straight to <a href="#layout">Program Layout</a> to learn about the
 221     layout of the source code tree.
 222
 223     <!------------------------------------------------------------------------->
 224     <h3><a name="terminology">Terminology and Notation</a></h3>
 225     <!------------------------------------------------------------------------->
 226
 227     <p>Throughout this manual, the following names are used to denote paths
 228     specific to the local system and working environment.  <i>These are not
 229     environment variables you need to set but just strings used in the rest
 230     of this document below</i>.  In any of the examples below, simply replace
 231     each of these names with the appropriate pathname on your local system.
 232     All these paths are absolute:</p>
 233     <dl compact>
 234         <dt>CVSROOTDIR
 235         <dd>
 236         This is the path for the CVS repository containing the LLVM source
 237         code.  Ask the person responsible for your local LLVM installation to
 238         give you this path.
 239         <p>
 240
 241         <dt>OBJ_ROOT
 242         <dd>
 243         This is the top level directory for where the LLVM suite object files
 244         will be placed during the build.
 245         <p>
 246
 247         <dt>LLVMGCCDIR
 248         <dd>
 249         This is the pathname to the location where the LLVM C Front End will
 250         be installed.  Note that  the C front end does not need to be installed
 251         during the LLVM suite build; you will just need to know where it will
 252         go for configuring the build system and running the test suite later.
 253         <p>
 254
 255         <dt>GCCSRC
 256         <dd>
 257         This is the pathname of the directory where the LLVM C front end source
 258         code can be found.
 259         <p>
 260
 261         <dt>GCCOBJ
 262         <dd>
 263         This is the pathname of the directory where the LLVM C front end object
 264         code will be placed during the build.  It can be safely removed once
 265         the build is complete.
 266     </dl>
 267
 268     <!------------------------------------------------------------------------->
 269     <h3><a name="environment">Setting up your environment</a></h3>
 270     <!------------------------------------------------------------------------->
 271
 272     <p>
 273     In order to compile and use LLVM, you will need to set some environment
 274     variables.  There are also some shell aliases which you may find useful.
 275     You can set these on the command line, or better yet, set them in your
 276     <tt>.cshrc</tt> or <tt>.profile</tt>.
 277
 278     <dl compact>
 279         <dt><tt>LLVM_LIB_SEARCH_PATH</tt>=<tt><i>LLVMGCCDIR</i>/llvm-gcc/bytecode-libs</tt>
 280         <dd>
 281         This environment variable helps the LLVM C front end find bytecode
 282         libraries that it will need for compilation.
 283         <p>
 284
 285         <dt><tt>PATH</tt>=<tt>${PATH}:<i>OBJ_ROOT</i>/llvm/tools/Debug</tt>
 286         <dd>
 287         Adding this directory to the end of your path will allow the
 288         compilation of the C front end to find the LLVM tools.  The LLVM tools
 289         are needed for the C front end compile.
 290         <p>
 291
 292         <dt><tt>CC</tt>=<i>Pathname to your GCC compiler</i>
 293         <dd>
 294         The GCC compiler that you want to use must be the first C compiler in
 295         your <tt>PATH</tt>.  Otherwise, set this variable so that
 296         <tt>configure</tt> will use the GCC compiler that you want to use.
 297         <p>
 298
 299         <dt><tt>CXX</tt>=<i>Pathname to your GCC C++ compiler</i>
 300         <dd>
 301         The GCC compiler that you want to use must be the first C++ compiler in
 302         your <tt>PATH</tt>.  Otherwise, set this variable so that
 303         <tt>configure</tt> will use the GCC compiler that you want to use.
 304         <p>
 305
 306         <dt><tt>CVSROOT</tt>=<i>CVSROOT</i>
 307         <dd>
 308         This environment variable tells CVS where to find the CVS repository.
 309         <p>
 310
 311         <dt>alias llvmgcc <i>LLVMGCCDIR</i><tt>/bin/llvm-gcc</tt>
 312         <dd>
 313         This alias allows you to use the LLVM C front end without putting it in
 314         your <tt>PATH</tt> or typing in its complete pathname.
 315     </dl>
 316
 317     <!------------------------------------------------------------------------->
 318     <h3><a name="checkout">Checkout LLVM from CVS</a></h3>
 319     <!------------------------------------------------------------------------->
 320
 321     <p>To get a fresh copy of the entire source code, all you
 322     need to do is check it out from CVS as follows:
 323     <ul>
 324     <li><tt>cd <i>where-you-want-llvm-to-live</i></tt>
 325     <li><tt>cvs -d <i>CVSROOTDIR</i> checkout llvm</tt></p>
 326     </ul>
 327
 328     <p>This will create an '<tt>llvm</tt>' directory in the current
 329     directory and fully populate it with the LLVM source code, Makefiles,
 330     test directories, and local copies of documentation files.</p>
 331
 332     <p>
 333     Note that the C front end is not included in the CVS repository.  You
 334     should have either downloaded the source, or better yet, downloaded the
 335     binary distribution for your platform.
 336     </p>
 337
 338     <!------------------------------------------------------------------------->
 339     <h3><a name="config">Local LLVM Configuration</a></h3>
 340     <!------------------------------------------------------------------------->
 341
 342     <p>Once checked out from the CVS repository, the LLVM suite source code
 343     must be configured via the <tt>configure</tt> script.  This script sets
 344     variables in <tt>llvm/Makefile.config</tt> and
 345     <tt>llvm/include/Config/config.h</tt>.
 346
 347     <p>
 348     The following environment variables are used by <tt>configure</tt> to
 349     configure Makefile.config:
 350     </p>
 351
 352     <ul>
 353         <p><li><i>CXX</i> = Pathname of the C++ compiler to use.
 354         <p><li><i>CC</i> = Pathname of the C compiler to use.
 355     </ul>
 356
 357     The following options can be used to set or enable LLVM specific options:
 358
 359     <dl compact>
 360     <dt><i>--with-objroot=OBJ_ROOT</i>
 361     <dd>
 362         Path to the directory where
 363                 object files, libraries, and executables should be placed.
 364         If this is set to <tt>.</tt>, then the object files will be placed
 365         within the source code tree.  If left unspecified, the default value is
 366         <tt>.</tt>.
 367                 (See the Section on <a href=#objfiles>
 368                 The location for LLVM object files</a>
 369                 for more information.)
 370         <p>
 371     <dt><i>--with-llvmgccdir=LLVMGCCDIR</i>
 372     <dd>
 373         Path to the location where the LLVM C front end binaries and
 374         associated libraries will be installed.
 375         <p>
 376     <dt><i>--enable-optimized</i>
 377     <dd>
 378         Enables optimized compilation (debugging symbols are removed and GCC
 379         optimization flags are enabled).  The default is to use an unoptimized
 380         build (also known as a debug build).
 381         <p>
 382     <dt><i>--enable-jit</i>
 383     <dd>
 384         Compile the Just In Time (JIT) functionality.  This is not available
 385         on all platforms.  The default is dependent on platform, so it is best
 386         to explicitly enable it if you want it.
 387     </dl>
 388
 389     In addition to running <tt>configure</tt>, you must set the
 390     <tt>LLVM_LIB_SEARCH_PATH</tt> environment variable in your startup scripts.
 391     This environment variable is used to locate "system" libraries like
 392     "<tt>-lc</tt>" and "<tt>-lm</tt>" when linking.  This variable should be set
 393     to the absolute path for the bytecode-libs subdirectory of the C front-end
 394     install, or LLVMGCCDIR/llvm-gcc/bytecode-libs.  For example, one might
 395     set <tt>LLVM_LIB_SEARCH_PATH</tt> to
 396     <tt>/home/vadve/lattner/local/x86/llvm-gcc/bytecode-libs</tt> for the X86
 397     version of the C front-end on our research machines.<p>
 398
 399     <!------------------------------------------------------------------------->
 400     <h3><a name="compile">Compiling the LLVM Suite Source Code</a></h3>
 401     <!------------------------------------------------------------------------->
 402
 403     Once you have configured LLVM, you can build it.  There are three types of
 404     builds:
 405
 406     <dl compact>
 407         <dt>Debug Builds
 408         <dd>
 409         These builds are the default.  They compile the tools and libraries
 410         with debugging information.
 411         <p>
 412
 413         <dt>Release (Optimized) Builds
 414         <dd>
 415         These builds are enabled with the <tt>--enable-optimized</tt> option to
 416         <tt>configure</tt>.  They compile the tools and libraries with GCC
 417         optimizer flags on and strip debugging information from the libraries
 418         and executables it generates.
 419         <p>
 420
 421         <dt>Profile Builds
 422         <dd>
 423         These builds are for use with profiling.  They compile profiling
 424         information into the code for use with programs like <tt>gprof</tt>.
 425         Profile builds must be started by setting variables on the
 426         <tt>make</tt> command line.
 427     </dl>
 428
 429     Once you have LLVM configured, you can build it by entering the top level
 430     <tt>llvm</tt> directory and issuing the following command:
 431     <p>
 432     <tt>make</tt>
 433
 434     <p>
 435     If you have multiple processors in your machine, you may wish to use some
 436     of the parallel build options provided by GNU Make.  For example, you could
 437     use the command:
 438     </p>
 439
 440     <p>
 441     <tt>make -j2</tt>
 442
 443     <p>
 444     There are several other targets which are useful when working with the LLVM
 445     source code:
 446
 447     <dl compact>
 448         <dt><tt>make clean</tt>
 449         <dd>
 450         Removes all files generated by the build.  This includes object files,
 451         generated C/C++ files, libraries, and executables.
 452         <p>
 453
 454         <dt><tt>make distclean</tt>
 455         <dd>
 456         Removes everything that <tt>make clean</tt> does, but also removes
 457         files generated by <tt>configure</tt>.  It attempts to return the
 458         source tree to the original state in which it was shipped.
 459         <p>
 460     </dl>
 461
 462     It is also possible to override default values from <tt>configure</tt> by
 463     declaring variables on the command line.  The following are some examples:
 464
 465     <dl compact>
 466         <dt><tt>make ENABLE_OPTIMIZED=1</tt>
 467         <dd>
 468         Perform a Release (Optimized) build.
 469         <p>
 470
 471         <dt><tt>make ENABLE_PROFILING=1</tt>
 472         <dd>
 473         Perform a Profiling build.
 474         <p>
 475
 476         <dt><tt>make VERBOSE=1</tt>
 477         <dd>
 478         Print what <tt>make</tt> is doing on standard output.
 479         <p>
 480     </dl>
 481
 482     Every directory in the LLVM source tree includes a <tt>Makefile</tt> to
 483     build it and any subdirectories that it contains.  Entering any directory
 484     inside the LLVM source tree and typing <tt>make</tt> should rebuild
 485     anything in or below that directory that is out of date.
 486
 487     <!------------------------------------------------------------------------->
 488     <h3><a name="build">Building the LLVM C Front End</a></h3>
 489     <!------------------------------------------------------------------------->
 490
 491     <b>
 492     <p>
 493     This step is optional if you have the C front end binary distrubtion for
 494     your platform.
 495     </p>
 496     </b>
 497
 498     Now that you have the LLVM Suite built, you can build the C front end.  For
 499     those of you that have built GCC before, the process is very similar.
 500     <p>
 501     Be forewarned, though: the build system for the C front end is not as
 502     polished as the rest of the LLVM code, so there will be many warnings and
 503     errors that you will need to ignore for now:
 504
 505     <ol>
 506         <li>Ensure that <tt><i>OBJ_ROOT</i>/llvm/tools/Debug</tt> is at the
 507         <i>end</i> of your <tt>PATH</tt> environment variable.
 508
 509         <li><tt>cd <i>GCCOBJ</i></tt>
 510
 511         <li>Configure the source code:
 512         <ul>
 513             <li>On Linux/x86, use
 514             <ul>
 515                 <li><tt><i>GCCSRC</i>/configure --prefix=<i>LLVMGCCDIR</i>
 516                 --enable-languages=c</tt>
 517             </ul>
 518
 519             <li>On Solaris/Sparc, use
 520             <ul>
 521                 <li><tt><i>GCCSRC</i>/configure --prefix=<i>LLVMGCCDIR</i>
 522                  --enable-languages=c --target=sparcv9-sun-solaris2</tt>
 523             </ul>
 524         </ul>
 525
 526         <li><tt>make bootstrap</tt>
 527
 528         <li>The build will eventually fail.  Don't worry; chances are good that
 529         everything that needed to build is built.
 530
 531         <li><tt>make install</tt>
 532     </ol>
 533
 534     At this point, you should have a working copy of the LLVM C front end
 535     installed in <i>LLVMGCCDIR</i>.
 536
 537     <!------------------------------------------------------------------------->
 538     <h3><a name="objfiles">The location for LLVM object files</a></h3>
 539     <!------------------------------------------------------------------------->
 540
 541     <p>The LLVM build system sends most output files generated during the build
 542     into the directory defined by the variable <i>OBJ_ROOT</i> in
 543     <tt>llvm/Makefile.config</tt>, which is set by the <i>--with-objroot</i>
 544     option in <tt>configure</tt>.  This can be either just your normal LLVM
 545     source tree or some other directory writable by you.  You may wish to put
 546     object files on a different filesystem either to keep them from being backed
 547     up or to speed up local builds.
 548
 549     <p>
 550     If <i>OBJ_ROOT</i> is specified, then the build system will create a
 551     directory tree underneath it that resembles the source code's pathname
 552     relative to your home directory.
 553     </p>
 554
 555     <p>
 556     For example, suppose that <i>OBJ_ROOT</i> is set to <tt>/tmp</tt> and the
 557     LLVM suite source code is located in <tt>/usr/home/joe/src/llvm</tt>, where
 558     <tt>/usr/home/joe</tt> is the home directory of a user named Joe.  Then,
 559     the object files will be placed in <tt>/tmp/src/llvm</tt>.
 560     </p>
 561
 562     <p>
 563     The LLVM build will place files underneath <i>OBJ_ROOT</i> in directories
 564     named after the build type:
 565     </p>
 566
 567     <dl compact>
 568         <dt>Debug Builds
 569         <dd>
 570         <dl compact>
 571             <dt>Tools
 572             <dd><tt><i>OBJ_ROOT</i>/llvm/tools/Debug</tt>
 573             <dt>Libraries
 574             <dd><tt><i>OBJ_ROOT</i>/llvm/lib/Debug</tt>
 575         </dl>
 576         <p>
 577
 578         <dt>Release Builds
 579         <dd>
 580         <dl compact>
 581             <dt>Tools
 582             <dd><tt><i>OBJ_ROOT</i>/llvm/tools/Release</tt>
 583             <dt>Libraries
 584             <dd><tt><i>OBJ_ROOT</i>/llvm/lib/Release</tt>
 585         </dl>
 586         <p>
 587
 588         <dt>Profile Builds
 589         <dd>
 590         <dl compact>
 591             <dt>Tools
 592             <dd><tt><i>OBJ_ROOT</i>/llvm/tools/Profile</tt>
 593             <dt>Libraries
 594             <dd><tt><i>OBJ_ROOT</i>/llvm/lib/Profile</tt>
 595         </dl>
 596     </dl>
 597
 598     <!--=====================================================================-->
 599     <center>
 600     <h2><a name="layout"><b>Program Layout</b></a></h2>
 601     </center>
 602     <!--=====================================================================-->
 603
 604     <p>One useful source of information about the LLVM source base is the LLVM <a
 605     href="http://www.doxygen.org">doxygen</a> documentation, available at <tt><a
 606     href="http://llvm.cs.uiuc.edu/doxygen/">http://llvm.cs.uiuc.edu/doxygen/</a></tt>. The
 607     following is a brief introduction to code layout:</p>
 608
 609
 610     <!------------------------------------------------------------------------->
 611     <h3><a name="cvsdir"><tt>CVS</tt> directories</a></h3>
 612     <!------------------------------------------------------------------------->
 613
 614     Every directory checked out of CVS will contain a <tt>CVS</tt> directory;
 615     for the most part these can just be ignored.
 616
 617
 618     <!------------------------------------------------------------------------->
 619     <h3><a name="include"><tt>llvm/include</tt></a></h3>
 620     <!------------------------------------------------------------------------->
 621
 622     This directory contains public header files exported from the LLVM
 623     library. The three main subdirectories of this directory are:<p>
 624
 625     <ol>
 626        <li><tt>llvm/include/llvm</tt> - This directory contains all of the LLVM
 627        specific header files.  This directory also has subdirectories for
 628        different portions of LLVM: <tt>Analysis</tt>, <tt>CodeGen</tt>,
 629        <tt>Reoptimizer</tt>, <tt>Target</tt>, <tt>Transforms</tt>, etc...
 630
 631        <li><tt>llvm/include/Support</tt> - This directory contains generic
 632        support libraries that are independent of LLVM, but are used by LLVM.
 633        For example, some C++ STL utilities and a Command Line option processing
 634        library.
 635
 636        <li><tt>llvm/include/Config</tt> - This directory contains header files
 637        configured by the <tt>configure</tt> script.  They wrap "standard" UNIX
 638        and C header files.  Source code can include these header files which
 639        automatically take care of the conditional #includes that the configure
 640        script generates.
 641     </ol>
 642
 643     <!------------------------------------------------------------------------->
 644     <h3><a name="lib"><tt>llvm/lib</tt></a></h3>
 645     <!------------------------------------------------------------------------->
 646
 647     This directory contains most of the source files of the LLVM system. In
 648     LLVM almost all
 649     code exists in libraries, making it very easy to share code among the
 650     different <a href="#tools">tools</a>.<p>
 651
 652      <dl compact>
 653       <dt><tt>llvm/lib/VMCore/</tt><dd> This directory holds the core LLVM
 654       source files that implement core classes like Instruction and BasicBlock.
 655
 656       <dt><tt>llvm/lib/AsmParser/</tt><dd> This directory holds the source code
 657       for the LLVM assembly language parser library.
 658
 659       <dt><tt>llvm/lib/ByteCode/</tt><dd> This directory holds code for reading
 660       and write LLVM bytecode.
 661
 662       <dt><tt>llvm/lib/CWriter/</tt><dd> This directory implements the LLVM to C
 663       converter.
 664
 665       <dt><tt>llvm/lib/Analysis/</tt><dd> This directory contains a variety of
 666       different program analyses, such as Dominator Information, Call Graphs,
 667       Induction Variables, Interval Identification, Natural Loop Identification,
 668       etc...
 669
 670       <dt><tt>llvm/lib/Transforms/</tt><dd> This directory contains the source
 671       code for the LLVM to LLVM program transformations, such as Aggressive Dead
 672       Code Elimination, Sparse Conditional Constant Propagation, Inlining, Loop
 673       Invarient Code Motion, Dead Global Elimination, Pool Allocation, and many
 674       others...
 675
 676       <dt><tt>llvm/lib/Target/</tt><dd> This directory contains files that
 677       describe various target architectures for code generation.  For example,
 678       the llvm/lib/Target/Sparc directory holds the Sparc machine
 679       description.<br>
 680
 681       <dt><tt>llvm/lib/CodeGen/</tt><dd> This directory contains the major parts
 682       of the code generator: Instruction Selector, Instruction Scheduling, and
 683       Register Allocation.
 684
 685       <dt><tt>llvm/lib/Reoptimizer/</tt><dd> This directory holds code related
 686       to the runtime reoptimizer framework that is currently under development.
 687
 688       <dt><tt>llvm/lib/Support/</tt><dd> This directory contains the source code
 689       that corresponds to the header files located in
 690       <tt>llvm/include/Support/</tt>.
 691     </dl>
 692
 693     <!------------------------------------------------------------------------->
 694     <h3><a name="test"><tt>llvm/test</tt></a></h3>
 695     <!------------------------------------------------------------------------->
 696
 697     <p>This directory contains regression tests and source code that is used to
 698     test the LLVM infrastructure...</p>
 699
 700     <!------------------------------------------------------------------------->
 701     <h3><a name="tools"><tt>llvm/tools</tt></a></h3>
 702     <!------------------------------------------------------------------------->
 703
 704     <p>The <b>tools</b> directory contains the executables built out of the
 705     libraries above, which form the main part of the user interface.  You can
 706     always get help for a tool by typing <tt>tool_name --help</tt>.  The
 707     following is a brief introduction to the most important tools.</p>
 708
 709     <dl compact>
 710       <dt><tt><b>as</b></tt><dd>The assembler transforms the human readable
 711       LLVM assembly to LLVM bytecode.<p>
 712
 713       <dt><tt><b>dis</b></tt><dd>The disassembler transforms the LLVM bytecode
 714       to human readable LLVM assembly.  Additionally it can convert LLVM
 715       bytecode to C, which is enabled with the <tt>-c</tt> option.<p>
 716
 717       <dt><tt><b>lli</b></tt><dd> <tt>lli</tt> is the LLVM interpreter, which
 718       can directly execute LLVM bytecode (although very slowly...). In addition
 719       to a simple interpreter, <tt>lli</tt> is also has debugger and tracing
 720       modes (entered by specifying <tt>-debug</tt> or <tt>-trace</tt> on the
 721       command line, respectively). Finally, for architectures that support it
 722       (currently only x86 and Sparc), by default, <tt>lli</tt> will function as
 723       a Just-In-Time compiler (if the functionality was compiled in), and will
 724       execute the code <i>much</i> faster than the interpreter.<p>
 725
 726       <dt><tt><b>llc</b></tt><dd> <tt>llc</tt> is the LLVM backend compiler,
 727       which translates LLVM bytecode to a SPARC or x86 assembly file.<p>
 728
 729       <dt><tt><b>llvmgcc</b></tt><dd> <tt>llvmgcc</tt> is a GCC based C frontend
 730       that has been retargeted to emit LLVM code as the machine code output.  It
 731       works just like any other GCC compiler, taking the typical <tt>-c, -S, -E,
 732       -o</tt> options that are typically used.  The source code for the
 733       <tt>llvmgcc</tt> tool is currently not included in the LLVM cvs tree
 734       because it is quite large and not very interesting.<p>
 735
 736       <ol>
 737         <dt><tt><b>gccas</b></tt><dd> This tool is invoked by the
 738         <tt>llvmgcc</tt> frontend as the "assembler" part of the compiler.  This
 739         tool actually assembles LLVM assembly to LLVM bytecode,
 740             performs a variety of optimizations,
 741         and outputs LLVM bytecode.  Thus when you invoke <tt>llvmgcc -c x.c -o
 742         x.o</tt>, you are causing <tt>gccas</tt> to be run, which writes the
 743         <tt>x.o</tt> file (which is an LLVM bytecode file that can be
 744         disassembled or manipulated just like any other bytecode file).  The
 745         command line interface to <tt>gccas</tt> is designed to be as close as
 746         possible to the <b>system</b> '<tt>as</tt>' utility so that the gcc
 747         frontend itself did not have to be modified to interface to a "weird"
 748         assembler.<p>
 749
 750         <dt><tt><b>gccld</b></tt><dd> <tt>gccld</tt> links together several LLVM
 751         bytecode files into one bytecode file and does some optimization.  It is
 752         the linker invoked by the gcc frontend when multiple .o files need to be
 753         linked together.  Like <tt>gccas</tt> the command line interface of
 754         <tt>gccld</tt> is designed to match the system linker, to aid
 755         interfacing with the GCC frontend.<p>
 756       </ol>
 757
 758       <dt><tt><b>opt</b></tt><dd> <tt>opt</tt> reads LLVM bytecode, applies a
 759       series of LLVM to LLVM transformations (which are specified on the command
 760       line), and then outputs the resultant bytecode.  The '<tt>opt --help</tt>'
 761       command is a good way to get a list of the program transformations
 762       available in LLVM.<p>
 763
 764
 765       <dt><tt><b>analyze</b></tt><dd> <tt>analyze</tt> is used to run a specific
 766       analysis on an input LLVM bytecode file and print out the results.  It is
 767       primarily useful for debugging analyses, or familiarizing yourself with
 768       what an analysis does.<p>
 769
 770     </dl>
 771
 772     <!--=====================================================================-->
 773     <h2><a name="tutorial">An example using the LLVM tool chain</h2>
 774     <!--=====================================================================-->
 775
 776     <ol>
 777     <li>First, create a simple C file, name it 'hello.c':
 778        <pre>
 779    #include &lt;stdio.h&gt;
 780    int main() {
 781      printf("hello world\n");
 782      return 0;
 783    }
 784        </pre>
 785
 786     <li>Next, compile the C file into a LLVM bytecode file:<p>
 787
 788       <tt>% llvmgcc hello.c -o hello</tt><p>
 789
 790       This will create two result files: <tt>hello</tt> and
 791       <tt>hello.bc</tt>. The <tt>hello.bc</tt> is the LLVM bytecode that
 792       corresponds the the compiled program and the library facilities that it
 793       required.  <tt>hello</tt> is a simple shell script that runs the bytecode
 794       file with <tt>lli</tt>, making the result directly executable.<p>
 795
 796     <li>Run the program. To make sure the program ran, execute one of the
 797     following commands:<p>
 798
 799       <tt>% ./hello</tt><p>
 800
 801       or<p>
 802
 803       <tt>% lli hello.bc</tt><p>
 804
 805     <li>Use the <tt>dis</tt> utility to take a look at the LLVM assembly
 806     code:<p>
 807
 808       <tt>% dis < hello.bc | less</tt><p>
 809
 810     <li>Compile the program to native Sparc assembly using the code
 811     generator (assuming you are currently on a Sparc system):<p>
 812
 813       <tt>% llc hello.bc -o hello.s</tt><p>
 814
 815     <li>Assemble the native sparc assemble file into a program:<p>
 816
 817       <tt>% /opt/SUNWspro/bin/cc -xarch=v9 hello.s -o hello.sparc</tt><p>
 818
 819     <li>Execute the native sparc program:<p>
 820
 821       <tt>% ./hello.sparc</tt><p>
 822
 823     </ol>
 824
 825
 826     <!--=====================================================================-->
 827     <h2><a name="help">Common Problems</a></h2>
 828     <!--=====================================================================-->
 829
 830     Below are common problems and their remedies:
 831
 832     <dl compact>
 833         <dt><b>When I run configure, it finds the wrong C compiler.</b>
 834         <dd>
 835         The <tt>configure</tt> script attempts to locate first <tt>gcc</tt> and
 836         then <tt>cc</tt>, unless it finds compiler paths set in <tt>CC</tt> and
 837         <tt>CXX</tt> for the C and C++ compiler, respectively.
 838
 839         If <tt>configure</tt> finds the wrong compiler, either adjust your
 840         <tt>PATH</tt> environment variable or set <tt>CC</tt> and <tt>CXX</tt>
 841         explicitly.
 842         <p>
 843
 844         <dt><b>I compile the code, and I get some error about /localhome</b>.
 845         <dd>
 846         There are several possible causes for this.  The first is that you
 847         didn't set a pathname properly when using <tt>configure</tt>, and it
 848         defaulted to a pathname that we use on our research machines.
 849         <p>
 850         Another possibility is that we hardcoded a path in our Makefiles.  If
 851         you see this, please email the LLVM bug mailing list with the name of
 852         the offending Makefile and a description of what is wrong with it.
 853
 854         <dt><b>The <tt>configure</tt> script finds the right C compiler, but it
 855         uses the LLVM linker from a previous build.  What do I do?</b>
 856         <dd>
 857         The <tt>configure</tt> script uses the <tt>PATH</tt> to find
 858         executables, so if it's grabbing the wrong linker/assembler/etc, there
 859         are two ways to fix it:
 860         <ol>
 861             <li>Adjust your <tt>PATH</tt> environment variable so that the
 862             correct program appears first in the <tt>PATH</tt>.  This may work,
 863             but may not be convenient when you want them <i>first</i> in your
 864             path for other work.
 865             <p>
 866
 867             <li>Run <tt>configure</tt> with an alternative <tt>PATH</tt> that
 868             is correct.  In a Borne compatible shell, the syntax would be:
 869             <p>
 870             <tt>PATH=<the path without the bad program> ./configure ...</tt>
 871             <p>
 872             This is still somewhat inconvenient, but it allows
 873             <tt>configure</tt> to do its work without having to adjust your
 874             <tt>PATH</tt> permanently.
 875         </ol>
 876     </dl>
 877
 878     <!--=====================================================================-->
 879     <h2><a name="links">Links</a></h2>
 880     <!--=====================================================================-->
 881
 882     <p>This document is just an <b>introduction</b> to how to use LLVM to do
 883     some simple things... there are many more interesting and complicated things
 884     that you can do that aren't documented here (but we'll gladly accept a patch
 885     if you want to write something up!).  For more information about LLVM, check
 886     out:</p>
 887
 888     <ul>
 889     <li><a href="http://llvm.cs.uiuc.edu/">LLVM homepage</a></li>
 890     <li><a href="http://llvm.cs.uiuc.edu/doxygen/">LLVM doxygen tree</a></li>
 891     <li><a href="http://llvm.cs.uiuc.edu/docs/Projects.html">Starting a Project that Uses LLVM</a></li>
 892     </ul>
 893
 894     <hr>
 895
 896     If you have any questions or run into any snags (or you have any
 897     additions...), please send an email to
 898     <a href="mailto:sabre@nondot.org">Chris Lattner</a>.</p>
 899
 900             <!-- Created: Mon Jul  1 02:29:02 CDT 2002 -->
 901             <!-- hhmts start -->
 902 Last modified: Tue Jun  3 22:06:43 CDT 2003
 903 <!-- hhmts end -->
 904   </body>
 905 </html>