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