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