docs/GettingStarted.html

   1 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN"
   2                       "http://www.w3.org/TR/html4/strict.dtd">
   3 <html>
   4 <head>
   5   <meta http-equiv="Content-Type" content="text/html; charset=utf-8">
   6   <title>Getting Started with LLVM System</title>
   7   <link rel="stylesheet" href="llvm.css" type="text/css">
   8 </head>
   9 <body>
  10
  11 <h1>
  12   Getting Started with the LLVM System
  13 </h1>
  14
  15 <ul>
  16   <li><a href="#overview">Overview</a>
  17   <li><a href="#quickstart">Getting Started Quickly (A Summary)</a>
  18   <li><a href="#requirements">Requirements</a>
  19     <ol>
  20       <li><a href="#hardware">Hardware</a></li>
  21       <li><a href="#software">Software</a></li>
  22       <li><a href="#brokengcc">Broken versions of GCC and other tools</a></li>
  23     </ol></li>
  24
  25   <li><a href="#starting">Getting Started with LLVM</a>
  26     <ol>
  27       <li><a href="#terminology">Terminology and Notation</a></li>
  28       <li><a href="#environment">Setting Up Your Environment</a></li>
  29       <li><a href="#unpack">Unpacking the LLVM Archives</a></li>
  30       <li><a href="#checkout">Checkout LLVM from Subversion</a></li>
  31       <li><a href="#git_mirror">LLVM GIT mirror</a></li>
  32       <li><a href="#installcf">Install the GCC Front End</a></li>
  33       <li><a href="#config">Local LLVM Configuration</a></li>
  34       <li><a href="#compile">Compiling the LLVM Suite Source Code</a></li>
  35       <li><a href="#cross-compile">Cross-Compiling LLVM</a></li>
  36       <li><a href="#objfiles">The Location of LLVM Object Files</a></li>
  37       <li><a href="#optionalconfig">Optional Configuration Items</a></li>
  38     </ol></li>
  39
  40   <li><a href="#layout">Program layout</a>
  41     <ol>
  42       <li><a href="#examples"><tt>llvm/examples</tt></a></li>
  43       <li><a href="#include"><tt>llvm/include</tt></a></li>
  44       <li><a href="#lib"><tt>llvm/lib</tt></a></li>
  45       <li><a href="#projects"><tt>llvm/projects</tt></a></li>
  46       <li><a href="#runtime"><tt>llvm/runtime</tt></a></li>
  47       <li><a href="#test"><tt>llvm/test</tt></a></li>
  48       <li><a href="#test-suite"><tt>test-suite</tt></a></li>
  49       <li><a href="#tools"><tt>llvm/tools</tt></a></li>
  50       <li><a href="#utils"><tt>llvm/utils</tt></a></li>
  51     </ol></li>
  52
  53   <li><a href="#tutorial">An Example Using the LLVM Tool Chain</a>
  54       <ol>
  55          <li><a href="#tutorial4">Example with llvm-gcc4</a></li>
  56       </ol>
  57   <li><a href="#problems">Common Problems</a>
  58   <li><a href="#links">Links</a>
  59 </ul>
  60
  61 <div class="doc_author">
  62   <p>Written by:
  63     <a href="mailto:criswell@uiuc.edu">John Criswell</a>,
  64     <a href="mailto:sabre@nondot.org">Chris Lattner</a>,
  65     <a href="http://misha.brukman.net/">Misha Brukman</a>,
  66     <a href="http://www.cs.uiuc.edu/~vadve">Vikram Adve</a>, and
  67     <a href="mailto:gshi1@uiuc.edu">Guochun Shi</a>.
  68   </p>
  69 </div>
  70
  71
  72 <!-- *********************************************************************** -->
  73 <h2>
  74   <a name="overview">Overview</a>
  75 </h2>
  76 <!-- *********************************************************************** -->
  77
  78 <div>
  79
  80 <p>Welcome to LLVM! In order to get started, you first need to know some
  81 basic information.</p>
  82
  83 <p>First, LLVM comes in three pieces. The first piece is the LLVM
  84 suite. This contains all of the tools, libraries, and header files
  85 needed to use the low level virtual machine.  It contains an
  86 assembler, disassembler, bitcode analyzer and bitcode optimizer.  It
  87 also contains basic regression tests that can be used to test the LLVM
  88 tools and the GCC front end.</p>
  89
  90 <p>The second piece is the GCC front end.  This component provides a version of
  91 GCC that compiles C and C++ code into LLVM bitcode.  Currently, the GCC front
  92 end uses the GCC parser to convert code to LLVM.  Once
  93 compiled into LLVM bitcode, a program can be manipulated with the LLVM tools
  94 from the LLVM suite.</p>
  95
  96 <p>
  97 There is a third, optional piece called Test Suite.  It is a suite of programs
  98 with a testing harness that can be used to further test LLVM's functionality
  99 and performance.
 100 </p>
 101
 102 </div>
 103
 104 <!-- *********************************************************************** -->
 105 <h2>
 106   <a name="quickstart">Getting Started Quickly (A Summary)</a>
 107 </h2>
 108 <!-- *********************************************************************** -->
 109
 110 <div>
 111
 112 <p>Here's the short story for getting up and running quickly with LLVM:</p>
 113
 114 <ol>
 115   <li>Read the documentation.</li>
 116   <li>Read the documentation.</li>
 117   <li>Remember that you were warned twice about reading the documentation.</li>
 118   <li>Install the llvm-gcc-4.2 front end if you intend to compile C or C++
 119       (see <a href="#installcf">Install the GCC Front End</a> for details):
 120     <ol>
 121       <li><tt>cd <i>where-you-want-the-C-front-end-to-live</i></tt></li>
 122       <li><tt>gunzip --stdout llvm-gcc-4.2-<i>version</i>-<i>platform</i>.tar.gz | tar -xvf -</tt></li>
 123           <li><tt><i>install-binutils-binary-from-MinGW</i></tt> (Windows only)</li>
 124           <li>Note: If the binary extension is "<tt>.bz</tt>" use <tt>bunzip2</tt> instead of <tt>gunzip</tt>.</li>
 125           <li>Note: On Windows, use <a href="http://www.7-zip.org/">7-Zip</a> or a similar archiving tool.</li>
 126           <li>Add <tt>llvm-gcc</tt>'s "<tt>bin</tt>" directory to your <tt>PATH</tt> environment variable.</li>
 127     </ol></li>
 128
 129   <li>Get the LLVM Source Code
 130   <ul>
 131     <li>With the distributed files (or use <a href="#checkout">SVN</a>):
 132     <ol>
 133       <li><tt>cd <i>where-you-want-llvm-to-live</i></tt>
 134       <li><tt>gunzip --stdout llvm-<i>version</i>.tar.gz | tar -xvf -</tt>
 135     </ol></li>
 136
 137   </ul></li>
 138
 139   <li><b>[Optional]</b> Get the Test Suite Source Code
 140   <ul>
 141     <li>With the distributed files (or use <a href="#checkout">SVN</a>):
 142     <ol>
 143       <li><tt>cd <i>where-you-want-llvm-to-live</i></tt>
 144       <li><tt>cd llvm/projects</tt>
 145       <li><tt>gunzip --stdout llvm-test-<i>version</i>.tar.gz | tar -xvf -</tt>
 146       <li><tt>mv llvm-test-<i>version</i> test-suite</tt>
 147     </ol></li>
 148
 149   </ul></li>
 150
 151
 152   <li>Configure the LLVM Build Environment
 153   <ol>
 154     <li><tt>cd <i>where-you-want-to-build-llvm</i></tt></li>
 155     <li><tt><i>/path/to/llvm/</i>configure [options]</tt><br>
 156     Some common options:
 157
 158       <ul>
 159         <li><tt>--prefix=<i>directory</i></tt>
 160         <p>Specify for <i>directory</i> the full pathname of where you
 161         want the LLVM tools and libraries to be installed (default
 162         <tt>/usr/local</tt>).</p></li>
 163         <li><tt>--with-llvmgccdir=<i>directory</i></tt>
 164         <p>Optionally, specify for <i>directory</i> the full pathname of the
 165         C/C++ front end installation to use with this LLVM configuration. If
 166         not specified, the PATH will be searched.  This is only needed if you
 167         want to run test-suite or do some special kinds of LLVM builds.</p></li>
 168         <li><tt>--enable-spec2000=<i>directory</i></tt>
 169             <p>Enable the SPEC2000 benchmarks for testing.  The SPEC2000
 170             benchmarks should be available in
 171             <tt><i>directory</i></tt>.</p></li>
 172       </ul>
 173   </ol></li>
 174
 175   <li>Build the LLVM Suite:
 176   <ol>
 177       <li><tt>gmake -k |&amp; tee gnumake.out
 178       &nbsp;&nbsp;&nbsp;# this is csh or tcsh syntax</tt></li>
 179       <li>If you get an "internal compiler error (ICE)" or test failures, see
 180           <a href="#brokengcc">below</a>.</li>
 181   </ol>
 182
 183 </ol>
 184
 185 <p>Consult the <a href="#starting">Getting Started with LLVM</a> section for
 186 detailed information on configuring and compiling LLVM.  See <a
 187 href="#environment">Setting Up Your Environment</a> for tips that simplify
 188 working with the GCC front end and LLVM tools.  Go to <a href="#layout">Program
 189 Layout</a> to learn about the layout of the source code tree.</p>
 190
 191 </div>
 192
 193 <!-- *********************************************************************** -->
 194 <h2>
 195   <a name="requirements">Requirements</a>
 196 </h2>
 197 <!-- *********************************************************************** -->
 198
 199 <div>
 200
 201 <p>Before you begin to use the LLVM system, review the requirements given below.
 202 This may save you some trouble by knowing ahead of time what hardware and
 203 software you will need.</p>
 204
 205 <!-- ======================================================================= -->
 206 <h3>
 207   <a name="hardware">Hardware</a>
 208 </h3>
 209
 210 <div>
 211
 212 <p>LLVM is known to work on the following platforms:</p>
 213
 214 <table cellpadding="3" summary="Known LLVM platforms">
 215 <tr>
 216   <th>OS</th>
 217   <th>Arch</th>
 218   <th>Compilers</th>
 219 </tr>
 220 <tr>
 221   <td>AuroraUX</td>
 222   <td>x86<sup><a href="#pf_1">1</a></sup></td>
 223   <td>GCC</td>
 224 </tr>
 225 <tr>
 226   <td>Linux</td>
 227   <td>x86<sup><a href="#pf_1">1</a></sup></td>
 228   <td>GCC</td>
 229 </tr>
 230 <tr>
 231   <td>Linux</td>
 232   <td>amd64</td>
 233   <td>GCC</td>
 234 </tr>
 235 <tr>
 236   <td>Solaris</td>
 237   <td>V9 (Ultrasparc)</td>
 238   <td>GCC</td>
 239 </tr>
 240 <tr>
 241   <td>FreeBSD</td>
 242   <td>x86<sup><a href="#pf_1">1</a></sup></td>
 243   <td>GCC</td>
 244 </tr>
 245 <tr>
 246   <td>FreeBSD</td>
 247   <td>amd64</td>
 248   <td>GCC</td>
 249 </tr>
 250 <tr>
 251   <td>MacOS X<sup><a href="#pf_2">2</a></sup></td>
 252   <td>PowerPC</td>
 253   <td>GCC</td>
 254 </tr>
 255 <tr>
 256   <td>MacOS X<sup><a href="#pf_2">2</a>,<a href="#pf_9">9</a></sup></td>
 257   <td>x86</td>
 258   <td>GCC</td>
 259 </tr>
 260 <tr>
 261   <td>Cygwin/Win32</td>
 262   <td>x86<sup><a href="#pf_1">1</a>,<a href="#pf_8">8</a>,
 263      <a href="#pf_11">11</a></sup></td>
 264   <td>GCC 3.4.X, binutils 2.20</td>
 265 </tr>
 266 <tr>
 267   <td>MinGW/Win32</td>
 268   <td>x86<sup><a href="#pf_1">1</a>,<a href="#pf_6">6</a>,
 269      <a href="#pf_8">8</a>, <a href="#pf_10">10</a>,
 270      <a href="#pf_11">11</a></sup></td>
 271   <td>GCC 3.4.X, binutils 2.20</td>
 272 </tr>
 273 </table>
 274
 275 <p>LLVM has partial support for the following platforms:</p>
 276
 277 <table summary="LLVM partial platform support">
 278 <tr>
 279   <th>OS</th>
 280   <th>Arch</th>
 281   <th>Compilers</th>
 282 </tr>
 283 <tr>
 284   <td>Windows</td>
 285   <td>x86<sup><a href="#pf_1">1</a></sup></td>
 286   <td>Visual Studio 2005 SP1 or higher<sup><a href="#pf_4">4</a>,<a href="#pf_5">5</a></sup></td>
 287 <tr>
 288   <td>AIX<sup><a href="#pf_3">3</a>,<a href="#pf_4">4</a></sup></td>
 289   <td>PowerPC</td>
 290   <td>GCC</td>
 291 </tr>
 292 <tr>
 293   <td>Linux<sup><a href="#pf_3">3</a>,<a href="#pf_5">5</a></sup></td>
 294   <td>PowerPC</td>
 295   <td>GCC</td>
 296 </tr>
 297
 298 <tr>
 299   <td>Linux<sup><a href="#pf_7">7</a></sup></td>
 300   <td>Alpha</td>
 301   <td>GCC</td>
 302 </tr>
 303 <tr>
 304   <td>Linux<sup><a href="#pf_7">7</a></sup></td>
 305   <td>Itanium (IA-64)</td>
 306   <td>GCC</td>
 307 </tr>
 308 <tr>
 309   <td>HP-UX<sup><a href="#pf_7">7</a></sup></td>
 310   <td>Itanium (IA-64)</td>
 311   <td>HP aCC</td>
 312 </tr>
 313 <tr>
 314   <td>Windows x64</td>
 315   <td>x86-64</td>
 316   <td>mingw-w64's GCC-4.5.x<sup><a href="#pf_12">12</a></sup></td>
 317 </tr>
 318 </table>
 319
 320 <p><b>Notes:</b></p>
 321
 322 <div class="doc_notes">
 323 <ol>
 324 <li><a name="pf_1">Code generation supported for Pentium processors and
 325 up</a></li>
 326 <li><a name="pf_2">Code generation supported for 32-bit ABI only</a></li>
 327 <li><a name="pf_3">No native code generation</a></li>
 328 <li><a name="pf_4">Build is not complete: one or more tools do not link or function</a></li>
 329 <li><a name="pf_5">The GCC-based C/C++ frontend does not build</a></li>
 330 <li><a name="pf_6">The port is done using the MSYS shell.</a></li>
 331 <li><a name="pf_7">Native code generation exists but is not complete.</a></li>
 332 <li><a name="pf_8">Binutils 2.20 or later is required to build the assembler
 333     generated by LLVM properly.</a></li>
 334 <li><a name="pf_9">XCode 2.5 and gcc 4.0.1</a> (Apple Build 5370) will trip
 335     internal LLVM assert messages when compiled for Release at optimization
 336     levels greater than 0 (i.e., <i>"-O1"</i> and higher).
 337     Add <i>OPTIMIZE_OPTION="-O0"</i> to the build command line
 338     if compiling for LLVM Release or bootstrapping the LLVM toolchain.</li>
 339 <li><a name="pf_10">For MSYS/MinGW on Windows, be sure to install the MSYS
 340     version of the perl package, and be sure it appears in your path
 341     before any Windows-based versions such as Strawberry Perl and
 342     ActivePerl, as these have Windows-specifics that will cause the
 343     build to fail.</a></li>
 344 <li><a name="pf_11">To use LLVM modules on Win32-based system,
 345     you may configure LLVM with <i>&quot;--enable-shared&quot;</i>.</a></li>
 346 <li><a name="pf_12">To compile SPU backend, you need to add
 347     <tt>&quot;LDFLAGS=-Wl,--stack,16777216&quot;</tt> to configure.</a></li>
 348 </ol>
 349 </div>
 350
 351 <p>Note that you will need about 1-3 GB of space for a full LLVM build in Debug
 352 mode, depending on the system (it is so large because of all the debugging
 353 information and the fact that the libraries are statically linked into multiple
 354 tools).  If you do not need many of the tools and you are space-conscious, you
 355 can pass <tt>ONLY_TOOLS="tools you need"</tt> to make.  The Release build
 356 requires considerably less space.</p>
 357
 358 <p>The LLVM suite <i>may</i> compile on other platforms, but it is not
 359 guaranteed to do so.  If compilation is successful, the LLVM utilities should be
 360 able to assemble, disassemble, analyze, and optimize LLVM bitcode.  Code
 361 generation should work as well, although the generated native code may not work
 362 on your platform.</p>
 363
 364 <p>The GCC front end is not very portable at the moment.  If you want to get it
 365 to work on another platform, you can download a copy of the source and <a
 366 href="GCCFEBuildInstrs.html">try to compile it</a> on your platform.</p>
 367
 368 </div>
 369
 370 <!-- ======================================================================= -->
 371 <h3>
 372   <a name="software">Software</a>
 373 </h3>
 374 <div>
 375   <p>Compiling LLVM requires that you have several software packages
 376   installed. The table below lists those required packages. The Package column
 377   is the usual name for the software package that LLVM depends on. The Version
 378   column provides "known to work" versions of the package. The Notes column
 379   describes how LLVM uses the package and provides other details.</p>
 380   <table summary="Packages required to compile LLVM">
 381     <tr><th>Package</th><th>Version</th><th>Notes</th></tr>
 382
 383     <tr>
 384       <td><a href="http://savannah.gnu.org/projects/make">GNU Make</a></td>
 385       <td>3.79, 3.79.1</td>
 386       <td>Makefile/build processor</td>
 387     </tr>
 388
 389     <tr>
 390       <td><a href="http://gcc.gnu.org/">GCC</a></td>
 391       <td>3.4.2</td>
 392       <td>C/C++ compiler<sup><a href="#sf1">1</a></sup></td>
 393     </tr>
 394
 395     <tr>
 396       <td><a href="http://www.gnu.org/software/texinfo/">TeXinfo</a></td>
 397       <td>4.5</td>
 398       <td>For building the CFE</td>
 399     </tr>
 400
 401     <tr>
 402       <td><a href="http://subversion.tigris.org/project_packages.html">SVN</a></td>
 403       <td>&ge;1.3</td>
 404       <td>Subversion access to LLVM<sup><a href="#sf2">2</a></sup></td>
 405     </tr>
 406
 407     <!-- FIXME:
 408     Do we support dg?
 409     Are DejaGnu and expect obsolete?
 410     Shall we mention Python? -->
 411
 412     <tr>
 413       <td><a href="http://savannah.gnu.org/projects/dejagnu">DejaGnu</a></td>
 414       <td>1.4.2</td>
 415       <td>Automated test suite<sup><a href="#sf3">3</a></sup></td>
 416     </tr>
 417
 418     <tr>
 419       <td><a href="http://www.tcl.tk/software/tcltk/">tcl</a></td>
 420       <td>8.3, 8.4</td>
 421       <td>Automated test suite<sup><a href="#sf3">3</a></sup></td>
 422     </tr>
 423
 424     <tr>
 425       <td><a href="http://expect.nist.gov/">expect</a></td>
 426       <td>5.38.0</td>
 427       <td>Automated test suite<sup><a href="#sf3">3</a></sup></td>
 428     </tr>
 429
 430     <tr>
 431       <td><a href="http://www.perl.com/download.csp">perl</a></td>
 432       <td>&ge;5.6.0</td>
 433       <td>Nightly tester, utilities</td>
 434     </tr>
 435
 436     <tr>
 437       <td><a href="http://savannah.gnu.org/projects/m4">GNU M4</a>
 438       <td>1.4</td>
 439       <td>Macro processor for configuration<sup><a href="#sf4">4</a></sup></td>
 440     </tr>
 441
 442     <tr>
 443       <td><a href="http://www.gnu.org/software/autoconf/">GNU Autoconf</a></td>
 444       <td>2.60</td>
 445       <td>Configuration script builder<sup><a href="#sf4">4</a></sup></td>
 446     </tr>
 447
 448     <tr>
 449       <td><a href="http://www.gnu.org/software/automake/">GNU Automake</a></td>
 450       <td>1.9.6</td>
 451       <td>aclocal macro generator<sup><a href="#sf4">4</a></sup></td>
 452     </tr>
 453
 454     <tr>
 455       <td><a href="http://savannah.gnu.org/projects/libtool">libtool</a></td>
 456       <td>1.5.22</td>
 457       <td>Shared library manager<sup><a href="#sf4">4</a></sup></td>
 458     </tr>
 459
 460   </table>
 461
 462   <p><b>Notes:</b></p>
 463   <div class="doc_notes">
 464   <ol>
 465     <li><a name="sf1">Only the C and C++ languages are needed so there's no
 466       need to build the other languages for LLVM's purposes.</a> See
 467       <a href="#brokengcc">below</a> for specific version info.</li>
 468     <li><a name="sf2">You only need Subversion if you intend to build from the
 469       latest LLVM sources. If you're working from a release distribution, you
 470       don't need Subversion.</a></li>
 471     <li><a name="sf3">Only needed if you want to run the automated test
 472       suite in the <tt>llvm/test</tt> directory.</a></li>
 473     <li><a name="sf4">If you want to make changes to the configure scripts,
 474       you will need GNU autoconf (2.60), and consequently, GNU M4 (version 1.4
 475       or higher). You will also need automake (1.9.6). We only use aclocal
 476       from that package.</a></li>
 477   </ol>
 478   </div>
 479
 480   <p>Additionally, your compilation host is expected to have the usual
 481   plethora of Unix utilities. Specifically:</p>
 482   <ul>
 483     <li><b>ar</b> - archive library builder</li>
 484     <li><b>bzip2*</b> - bzip2 command for distribution generation</li>
 485     <li><b>bunzip2*</b> - bunzip2 command for distribution checking</li>
 486     <li><b>chmod</b> - change permissions on a file</li>
 487     <li><b>cat</b> - output concatenation utility</li>
 488     <li><b>cp</b> - copy files</li>
 489     <li><b>date</b> - print the current date/time </li>
 490     <li><b>echo</b> - print to standard output</li>
 491     <li><b>egrep</b> - extended regular expression search utility</li>
 492     <li><b>find</b> - find files/dirs in a file system</li>
 493     <li><b>grep</b> - regular expression search utility</li>
 494     <li><b>gzip*</b> - gzip command for distribution generation</li>
 495     <li><b>gunzip*</b> - gunzip command for distribution checking</li>
 496     <li><b>install</b> - install directories/files </li>
 497     <li><b>mkdir</b> - create a directory</li>
 498     <li><b>mv</b> - move (rename) files</li>
 499     <li><b>ranlib</b> - symbol table builder for archive libraries</li>
 500     <li><b>rm</b> - remove (delete) files and directories</li>
 501     <li><b>sed</b> - stream editor for transforming output</li>
 502     <li><b>sh</b> - Bourne shell for make build scripts</li>
 503     <li><b>tar</b> - tape archive for distribution generation</li>
 504     <li><b>test</b> - test things in file system</li>
 505     <li><b>unzip*</b> - unzip command for distribution checking</li>
 506     <li><b>zip*</b> - zip command for distribution generation</li>
 507   </ul>
 508 </div>
 509
 510 <!-- ======================================================================= -->
 511 <h3>
 512   <a name="brokengcc">Broken versions of GCC and other tools</a>
 513 </h3>
 514
 515 <div>
 516
 517 <p>LLVM is very demanding of the host C++ compiler, and as such tends to expose
 518 bugs in the compiler.  In particular, several versions of GCC crash when trying
 519 to compile LLVM.  We routinely use GCC 4.2 (and higher) or Clang.
 520 Other versions of GCC will probably work as well.  GCC versions listed
 521 here are known to not work.  If you are using one of these versions, please try
 522 to upgrade your GCC to something more recent.  If you run into a problem with a
 523 version of GCC not listed here, please <a href="mailto:llvmdev@cs.uiuc.edu">let
 524 us know</a>.  Please use the "<tt>gcc -v</tt>" command to find out which version
 525 of GCC you are using.
 526 </p>
 527
 528 <p><b>GCC versions prior to 3.0</b>: GCC 2.96.x and before had several
 529 problems in the STL that effectively prevent it from compiling LLVM.
 530 </p>
 531
 532 <p><b>GCC 3.2.2 and 3.2.3</b>: These versions of GCC fails to compile LLVM with
 533 a bogus template error.  This was fixed in later GCCs.</p>
 534
 535 <p><b>GCC 3.3.2</b>: This version of GCC suffered from a <a
 536 href="http://gcc.gnu.org/PR13392">serious bug</a> which causes it to crash in
 537 the "<tt>convert_from_eh_region_ranges_1</tt>" GCC function.</p>
 538
 539 <p><b>Cygwin GCC 3.3.3</b>: The version of GCC 3.3.3 commonly shipped with
 540    Cygwin does not work.  Please <a href="GCCFEBuildInstrs.html#cygwin">upgrade
 541    to a newer version</a> if possible.</p>
 542 <p><b>SuSE GCC 3.3.3</b>: The version of GCC 3.3.3 shipped with SuSE 9.1 (and
 543    possibly others) does not compile LLVM correctly (it appears that exception
 544    handling is broken in some cases).  Please download the FSF 3.3.3 or upgrade
 545    to a newer version of GCC.</p>
 546 <p><b>GCC 3.4.0 on linux/x86 (32-bit)</b>: GCC miscompiles portions of the
 547    code generator, causing an infinite loop in the llvm-gcc build when built
 548    with optimizations enabled (i.e. a release build).</p>
 549 <p><b>GCC 3.4.2 on linux/x86 (32-bit)</b>: GCC miscompiles portions of the
 550    code generator at -O3, as with 3.4.0.  However gcc 3.4.2 (unlike 3.4.0)
 551    correctly compiles LLVM at -O2.  A work around is to build release LLVM
 552    builds with "make ENABLE_OPTIMIZED=1 OPTIMIZE_OPTION=-O2 ..."</p>
 553 <p><b>GCC 3.4.x on X86-64/amd64</b>: GCC <a href="http://llvm.org/PR1056">
 554    miscompiles portions of LLVM</a>.</p>
 555 <p><b>GCC 3.4.4 (CodeSourcery ARM 2005q3-2)</b>: this compiler miscompiles LLVM
 556    when building with optimizations enabled.  It appears to work with
 557    "<tt>make ENABLE_OPTIMIZED=1 OPTIMIZE_OPTION=-O1</tt>" or build a debug
 558    build.</p>
 559 <p><b>IA-64 GCC 4.0.0</b>: The IA-64 version of GCC 4.0.0 is known to
 560    miscompile LLVM.</p>
 561 <p><b>Apple Xcode 2.3</b>: GCC crashes when compiling LLVM at -O3 (which is the
 562    default with ENABLE_OPTIMIZED=1.  To work around this, build with
 563    "ENABLE_OPTIMIZED=1 OPTIMIZE_OPTION=-O2".</p>
 564 <p><b>GCC 4.1.1</b>: GCC fails to build LLVM with template concept check errors
 565       compiling some files.  At the time of this writing, GCC mainline (4.2)
 566       did not share the problem.</p>
 567 <p><b>GCC 4.1.1 on X86-64/amd64</b>: GCC <a href="http://llvm.org/PR1063">
 568    miscompiles portions of LLVM</a> when compiling llvm itself into 64-bit
 569    code.  LLVM will appear to mostly work but will be buggy, e.g. failing
 570    portions of its testsuite.</p>
 571 <p><b>GCC 4.1.2 on OpenSUSE</b>: Seg faults during libstdc++ build and on x86_64
 572 platforms compiling md5.c gets a mangled constant.</p>
 573 <p><b>GCC 4.1.2 (20061115 (prerelease) (Debian 4.1.1-21)) on Debian</b>: Appears
 574 to miscompile parts of LLVM 2.4. One symptom is ValueSymbolTable complaining
 575 about symbols remaining in the table on destruction.</p>
 576 <p><b>GCC 4.1.2 20071124 (Red Hat 4.1.2-42)</b>: Suffers from the same symptoms
 577 as the previous one. It appears to work with ENABLE_OPTIMIZED=0 (the default).</p>
 578 <p><b>Cygwin GCC 4.3.2 20080827 (beta) 2</b>:
 579   Users <a href="http://llvm.org/PR4145">reported</a> various problems related
 580   with link errors when using this GCC version.</p>
 581 <p><b>Debian GCC 4.3.2 on X86</b>: Crashes building some files in LLVM 2.6.</p>
 582 <p><b>GCC 4.3.3 (Debian 4.3.3-10) on ARM</b>: Miscompiles parts of LLVM 2.6
 583 when optimizations are turned on. The symptom is an infinite loop in
 584 FoldingSetImpl::RemoveNode while running the code generator.</p>
 585 <p><b>GCC 4.3.5 and GCC 4.4.5 on ARM</b>: These can miscompile <tt>value >>
 586 1</tt> even at -O0. A test failure in <tt>test/Assembler/alignstack.ll</tt> is
 587 one symptom of the problem.
 588 <p><b>GNU ld 2.16.X</b>. Some 2.16.X versions of the ld linker will produce very
 589 long warning messages complaining that some ".gnu.linkonce.t.*" symbol was
 590 defined in a discarded section. You can safely ignore these messages as they are
 591 erroneous and the linkage is correct.  These messages disappear using ld
 592 2.17.</p>
 593
 594 <p><b>GNU binutils 2.17</b>: Binutils 2.17 contains <a
 595 href="http://sourceware.org/bugzilla/show_bug.cgi?id=3111">a bug</a> which
 596 causes huge link times (minutes instead of seconds) when building LLVM.  We
 597 recommend upgrading to a newer version (2.17.50.0.4 or later).</p>
 598
 599 <p><b>GNU Binutils 2.19.1 Gold</b>: This version of Gold contained
 600 <a href="http://sourceware.org/bugzilla/show_bug.cgi?id=9836">a bug</a>
 601 which causes intermittent failures when building LLVM with position independent
 602 code.  The symptom is an error about cyclic dependencies.  We recommend
 603 upgrading to a newer version of Gold.</p>
 604
 605 </div>
 606
 607 </div>
 608
 609 <!-- *********************************************************************** -->
 610 <h2>
 611   <a name="starting">Getting Started with LLVM</a>
 612 </h2>
 613 <!-- *********************************************************************** -->
 614
 615 <div>
 616
 617 <p>The remainder of this guide is meant to get you up and running with
 618 LLVM and to give you some basic information about the LLVM environment.</p>
 619
 620 <p>The later sections of this guide describe the <a
 621 href="#layout">general layout</a> of the the LLVM source tree, a <a
 622 href="#tutorial">simple example</a> using the LLVM tool chain, and <a
 623 href="#links">links</a> to find more information about LLVM or to get
 624 help via e-mail.</p>
 625
 626 <!-- ======================================================================= -->
 627 <h3>
 628   <a name="terminology">Terminology and Notation</a>
 629 </h3>
 630
 631 <div>
 632
 633 <p>Throughout this manual, the following names are used to denote paths
 634 specific to the local system and working environment.  <i>These are not
 635 environment variables you need to set but just strings used in the rest
 636 of this document below</i>.  In any of the examples below, simply replace
 637 each of these names with the appropriate pathname on your local system.
 638 All these paths are absolute:</p>
 639
 640 <dl>
 641     <dt>SRC_ROOT
 642     <dd>
 643     This is the top level directory of the LLVM source tree.
 644     <br><br>
 645
 646     <dt>OBJ_ROOT
 647     <dd>
 648     This is the top level directory of the LLVM object tree (i.e. the
 649     tree where object files and compiled programs will be placed.  It
 650     can be the same as SRC_ROOT).
 651     <br><br>
 652
 653     <dt>LLVMGCCDIR
 654     <dd>
 655     This is where the LLVM GCC Front End is installed.
 656     <p>
 657     For the pre-built GCC front end binaries, the LLVMGCCDIR is
 658     <tt>llvm-gcc/<i>platform</i>/llvm-gcc</tt>.
 659 </dl>
 660
 661 </div>
 662
 663 <!-- ======================================================================= -->
 664 <h3>
 665   <a name="environment">Setting Up Your Environment</a>
 666 </h3>
 667
 668 <div>
 669
 670 <p>
 671 In order to compile and use LLVM, you may need to set some environment
 672 variables.
 673
 674 <dl>
 675   <dt><tt>LLVM_LIB_SEARCH_PATH</tt>=<tt>/path/to/your/bitcode/libs</tt></dt>
 676   <dd>[Optional] This environment variable helps LLVM linking tools find the
 677   locations of your bitcode libraries. It is provided only as a
 678   convenience since you can specify the paths using the -L options of the
 679   tools and the C/C++ front-end will automatically use the bitcode files
 680   installed in its
 681   <tt>lib</tt> directory.</dd>
 682 </dl>
 683
 684 </div>
 685
 686 <!-- ======================================================================= -->
 687 <h3>
 688   <a name="unpack">Unpacking the LLVM Archives</a>
 689 </h3>
 690
 691 <div>
 692
 693 <p>
 694 If you have the LLVM distribution, you will need to unpack it before you
 695 can begin to compile it.  LLVM is distributed as a set of two files: the LLVM
 696 suite and the LLVM GCC front end compiled for your platform.  There is an
 697 additional test suite that is optional.  Each file is a TAR archive that is
 698 compressed with the gzip program.
 699 </p>
 700
 701 <p>The files are as follows, with <em>x.y</em> marking the version number:
 702 <dl>
 703   <dt><tt>llvm-x.y.tar.gz</tt></dt>
 704   <dd>Source release for the LLVM libraries and tools.<br></dd>
 705
 706   <dt><tt>llvm-test-x.y.tar.gz</tt></dt>
 707   <dd>Source release for the LLVM test-suite.</dd>
 708
 709   <dt><tt>llvm-gcc-4.2-x.y.source.tar.gz</tt></dt>
 710   <dd>Source release of the llvm-gcc-4.2 front end.  See README.LLVM in the root
 711       directory for build instructions.<br></dd>
 712
 713   <dt><tt>llvm-gcc-4.2-x.y-platform.tar.gz</tt></dt>
 714   <dd>Binary release of the llvm-gcc-4.2 front end for a specific platform.<br></dd>
 715
 716 </dl>
 717
 718 </div>
 719
 720 <!-- ======================================================================= -->
 721 <h3>
 722   <a name="checkout">Checkout LLVM from Subversion</a>
 723 </h3>
 724
 725 <div>
 726
 727 <p>If you have access to our Subversion repository, you can get a fresh copy of
 728 the entire source code.  All you need to do is check it out from Subversion as
 729 follows:</p>
 730
 731 <ul>
 732   <li><tt>cd <i>where-you-want-llvm-to-live</i></tt></li>
 733   <li>Read-Only: <tt>svn co http://llvm.org/svn/llvm-project/llvm/trunk llvm</tt></li>
 734   <li>Read-Write:<tt>svn co https://user@llvm.org/svn/llvm-project/llvm/trunk
 735     llvm</tt></li>
 736 </ul>
 737
 738
 739 <p>This will create an '<tt>llvm</tt>' directory in the current
 740 directory and fully populate it with the LLVM source code, Makefiles,
 741 test directories, and local copies of documentation files.</p>
 742
 743 <p>If you want to get a specific release (as opposed to the most recent
 744 revision), you can checkout it from the '<tt>tags</tt>' directory (instead of
 745 '<tt>trunk</tt>'). The following releases are located in the following
 746 subdirectories of the '<tt>tags</tt>' directory:</p>
 747
 748 <ul>
 749 <li>Release 2.9: <b>RELEASE_29/final</b></li>
 750 <li>Release 2.8: <b>RELEASE_28</b></li>
 751 <li>Release 2.7: <b>RELEASE_27</b></li>
 752 <li>Release 2.6: <b>RELEASE_26</b></li>
 753 <li>Release 2.5: <b>RELEASE_25</b></li>
 754 <li>Release 2.4: <b>RELEASE_24</b></li>
 755 <li>Release 2.3: <b>RELEASE_23</b></li>
 756 <li>Release 2.2: <b>RELEASE_22</b></li>
 757 <li>Release 2.1: <b>RELEASE_21</b></li>
 758 <li>Release 2.0: <b>RELEASE_20</b></li>
 759 <li>Release 1.9: <b>RELEASE_19</b></li>
 760 <li>Release 1.8: <b>RELEASE_18</b></li>
 761 <li>Release 1.7: <b>RELEASE_17</b></li>
 762 <li>Release 1.6: <b>RELEASE_16</b></li>
 763 <li>Release 1.5: <b>RELEASE_15</b></li>
 764 <li>Release 1.4: <b>RELEASE_14</b></li>
 765 <li>Release 1.3: <b>RELEASE_13</b></li>
 766 <li>Release 1.2: <b>RELEASE_12</b></li>
 767 <li>Release 1.1: <b>RELEASE_11</b></li>
 768 <li>Release 1.0: <b>RELEASE_1</b></li>
 769 </ul>
 770
 771 <p>If you would like to get the LLVM test suite (a separate package as of 1.4),
 772 you get it from the Subversion repository:</p>
 773
 774 <div class="doc_code">
 775 <pre>
 776 % cd llvm/projects
 777 % svn co http://llvm.org/svn/llvm-project/test-suite/trunk test-suite
 778 </pre>
 779 </div>
 780
 781 <p>By placing it in the <tt>llvm/projects</tt>, it will be automatically
 782 configured by the LLVM configure script as well as automatically updated when
 783 you run <tt>svn update</tt>.</p>
 784
 785 <p>If you would like to get the GCC front end source code, you can also get it
 786 and build it yourself.  Please follow <a href="GCCFEBuildInstrs.html">these
 787 instructions</a> to successfully get and build the LLVM GCC front-end.</p>
 788
 789 </div>
 790
 791 <!-- ======================================================================= -->
 792 <h3>
 793   <a name="git_mirror">GIT mirror</a>
 794 </h3>
 795
 796 <div>
 797
 798 <p>GIT mirrors are available for a number of LLVM subprojects. These mirrors
 799   sync automatically with each Subversion commit and contain all necessary
 800   git-svn marks (so, you can recreate git-svn metadata locally). Note that right
 801   now mirrors reflect only <tt>trunk</tt> for each project. You can do the
 802   read-only GIT clone of LLVM via:</p>
 803
 804 <pre class="doc_code">
 805 git clone http://llvm.org/git/llvm.git
 806 </pre>
 807
 808 <p>If you want to check out clang too, run:</p>
 809
 810 <pre class="doc_code">
 811 git clone http://llvm.org/git/llvm.git
 812 cd llvm/tools
 813 git clone http://llvm.org/git/clang.git
 814 </pre>
 815
 816 <p>
 817 Since the upstream repository is in Subversion, you should use
 818 <tt>&quot;git pull --rebase&quot;</tt>
 819 instead of <tt>&quot;git pull&quot;</tt> to avoid generating a non-linear
 820 history in your clone.
 821 To configure <tt>&quot;git pull&quot;</tt> to pass <tt>--rebase</tt> by default
 822 on the master branch, run the following command:
 823 </p>
 824
 825 <pre class="doc_code">
 826 git config branch.master.rebase true
 827 </pre>
 828
 829 <h4>Sending patches with Git</h4>
 830 <div>
 831 <p>
 832 Please read <a href="DeveloperPolicy.html#patches">Developer Policy</a>, too.
 833 </p>
 834
 835 <p>
 836 Assume <tt>master</tt> points the upstream and <tt>mybranch</tt> points your
 837 working branch, and <tt>mybranch</tt> is rebased onto <tt>master</tt>.
 838 At first you may check sanity of whitespaces:
 839 </p>
 840
 841 <pre class="doc_code">
 842 git diff --check master..mybranch
 843 </pre>
 844
 845 <p>
 846 The easiest way to generate a patch is as below:
 847 </p>
 848
 849 <pre class="doc_code">
 850 git diff master..mybranch &gt; /path/to/mybranch.diff
 851 </pre>
 852
 853 <p>
 854 It is a little different from svn-generated diff. git-diff-generated diff has
 855 prefixes like <tt>a/</tt> and <tt>b/</tt>. Don't worry, most developers might
 856 know it could be accepted with <tt>patch -p1 -N</tt>.
 857 </p>
 858
 859 <p>
 860 But you may generate patchset with git-format-patch. It generates
 861 by-each-commit patchset. To generate patch files to attach to your article:
 862 </p>
 863
 864 <pre class="doc_code">
 865 git format-patch --no-attach master..mybranch -o /path/to/your/patchset
 866 </pre>
 867
 868 <p>
 869 If you would like to send patches directly, you may use git-send-email or
 870 git-imap-send. Here is an example to generate the patchset in Gmail's [Drafts].
 871 </p>
 872
 873 <pre class="doc_code">
 874 git format-patch --attach master..mybranch --stdout | git imap-send
 875 </pre>
 876
 877 <p>
 878 Then, your .git/config should have [imap] sections.
 879 </p>
 880
 881 <pre class="doc_code">
 882 [imap]
 883         host = imaps://imap.gmail.com
 884         user = <em>your.gmail.account</em>@gmail.com
 885         pass = <em>himitsu!</em>
 886         port = 993
 887         sslverify = false
 888 ; in English
 889         folder = "[Gmail]/Drafts"
 890 ; example for Japanese, "Modified UTF-7" encoded.
 891         folder = "[Gmail]/&amp;Tgtm+DBN-"
 892 ; example for Traditional Chinese
 893         folder = "[Gmail]/&amp;g0l6Pw-"
 894 </pre>
 895
 896 </div>
 897
 898 <h4>For developers to work with git-svn</h4>
 899 <div>
 900
 901 <p>To set up clone from which you can submit code using
 902    <tt>git-svn</tt>, run:</p>
 903
 904 <pre class="doc_code">
 905 git clone http://llvm.org/git/llvm.git
 906 cd llvm
 907 git svn init https://llvm.org/svn/llvm-project/llvm/trunk --username=&lt;username>
 908 git config svn-remote.svn.fetch :refs/remotes/origin/master
 909 git svn rebase -l  # -l avoids fetching ahead of the git mirror.
 910
 911 # If you have clang too:
 912 cd tools
 913 git clone http://llvm.org/git/clang.git
 914 cd clang
 915 git svn init https://llvm.org/svn/llvm-project/cfe/trunk --username=&lt;username>
 916 git config svn-remote.svn.fetch :refs/remotes/origin/master
 917 git svn rebase -l
 918 </pre>
 919
 920 <p>To update this clone without generating git-svn tags that conflict
 921 with the upstream git repo, run:</p>
 922
 923 <pre class="doc_code">
 924 git fetch && (cd tools/clang && git fetch)  # Get matching revisions of both trees.
 925 git checkout master
 926 git svn rebase -l
 927 (cd tools/clang &&
 928  git checkout master &&
 929  git svn rebase -l)
 930 </pre>
 931
 932 <p>This leaves your working directories on their master branches, so
 933 you'll need to <tt>checkout</tt> each working branch individually and
 934 <tt>rebase</tt> it on top of its parent branch.  (Note: This script is
 935 intended for relative newbies to git.  If you have more experience,
 936 you can likely improve on it.)</p>
 937
 938 <p>The git-svn metadata can get out of sync after you mess around with
 939 branches and <code>dcommit</code>. When that happens, <code>git svn
 940 dcommit</code> stops working, complaining about files with uncommitted
 941 changes. The fix is to rebuild the metadata:</p>
 942
 943 <pre class="doc_code">
 944 rm -rf .git/svn
 945 git svn rebase -l
 946 </pre>
 947
 948 </div>
 949
 950 </div>
 951
 952 <!-- ======================================================================= -->
 953 <h3>
 954   <a name="installcf">Install the GCC Front End</a>
 955 </h3>
 956
 957 <div>
 958
 959 <p>Before configuring and compiling the LLVM suite (or if you want to use just the LLVM
 960 GCC front end) you can optionally extract the front end from the binary distribution.
 961 It is used for running the LLVM test-suite and for compiling C/C++ programs.  Note that
 962 you can optionally <a href="GCCFEBuildInstrs.html">build llvm-gcc yourself</a> after building the
 963 main LLVM repository.</p>
 964
 965 <p>To install the GCC front end, do the following (on Windows, use an archival tool
 966 like <a href="http://www.7-zip.org/">7-zip</a> that understands gzipped tars):</p>
 967
 968 <ol>
 969   <li><tt>cd <i>where-you-want-the-front-end-to-live</i></tt></li>
 970   <li><tt>gunzip --stdout llvm-gcc-4.2-<i>version</i>-<i>platform</i>.tar.gz | tar -xvf
 971       -</tt></li>
 972 </ol>
 973
 974 <p>Once the binary is uncompressed, if you're using a *nix-based system, add a symlink for
 975 <tt>llvm-gcc</tt> and <tt>llvm-g++</tt> to some directory in your path.  If you're using a
 976 Windows-based system, add the <tt>bin</tt> subdirectory of your front end installation directory
 977 to your <tt>PATH</tt> environment variable.  For example, if you uncompressed the binary to
 978 <tt>c:\llvm-gcc</tt>, add <tt>c:\llvm-gcc\bin</tt> to your <tt>PATH</tt>.</p>
 979
 980 <p>If you now want to build LLVM from source, when you configure LLVM, it will
 981 automatically detect <tt>llvm-gcc</tt>'s presence (if it is in your path) enabling its
 982 use in test-suite.  Note that you can always build or install <tt>llvm-gcc</tt> at any
 983 point after building the main LLVM repository: just reconfigure llvm and
 984 test-suite will pick it up.
 985 </p>
 986
 987 <p>As a convenience for Windows users, the front end binaries for MinGW/x86 include
 988 versions of the required w32api and mingw-runtime binaries.  The last remaining step for
 989 Windows users is to simply uncompress the binary binutils package from
 990 <a href="http://mingw.org/">MinGW</a> into your front end installation directory.  While the
 991 front end installation steps are not quite the same as a typical manual MinGW installation,
 992 they should be similar enough to those who have previously installed MinGW on Windows systems.</p>
 993
 994 <p>To install binutils on Windows:</p>
 995
 996 <ol>
 997   <li><tt><i>download GNU Binutils from <a href="http://sourceforge.net/projects/mingw/files/">MinGW Downloads</a></i></tt></li>
 998   <li><tt>cd <i>where-you-uncompressed-the-front-end</i></tt></li>
 999   <li><tt><i>uncompress archived binutils directories (not the tar file) into the current directory</i></tt></li>
1000 </ol>
1001
1002 <p>The binary versions of the LLVM GCC front end may not suit all of your needs.  For
1003 example, the binary distribution may include an old version of a system header
1004 file, not "fix" a header file that needs to be fixed for GCC, or it may be linked with
1005 libraries not available on your system.  In cases like these, you may want to try
1006 <a href="GCCFEBuildInstrs.html">building the GCC front end from source</a>.  Thankfully,
1007 this is much easier now than it was in the past.</p>
1008
1009 <p>We also do not currently support updating of the GCC front end by manually overlaying
1010 newer versions of the w32api and mingw-runtime binary packages that may become available
1011 from MinGW.  At this time, it's best to think of the MinGW LLVM GCC front end binary as
1012 a self-contained convenience package that requires Windows users to simply download and
1013 uncompress the GNU Binutils binary package from the MinGW project.</p>
1014
1015 <p>Regardless of your platform, if you discover that installing the LLVM GCC front end
1016 binaries is not as easy as previously described, or you would like to suggest improvements,
1017 please let us know how you would like to see things improved by dropping us a note on our
1018 <a href="http://llvm.org/docs/#maillist">mailing list</a>.</p>
1019
1020 </div>
1021
1022 <!-- ======================================================================= -->
1023 <h3>
1024   <a name="config">Local LLVM Configuration</a>
1025 </h3>
1026
1027 <div>
1028
1029   <p>Once checked out from the Subversion repository, the LLVM suite source
1030   code must be
1031 configured via the <tt>configure</tt> script.  This script sets variables in the
1032 various <tt>*.in</tt> files, most notably <tt>llvm/Makefile.config</tt> and
1033 <tt>llvm/include/Config/config.h</tt>.  It also populates <i>OBJ_ROOT</i> with
1034 the Makefiles needed to begin building LLVM.</p>
1035
1036 <p>The following environment variables are used by the <tt>configure</tt>
1037 script to configure the build system:</p>
1038
1039 <table summary="LLVM configure script environment variables">
1040   <tr><th>Variable</th><th>Purpose</th></tr>
1041   <tr>
1042     <td>CC</td>
1043     <td>Tells <tt>configure</tt> which C compiler to use.  By default,
1044         <tt>configure</tt> will look for the first GCC C compiler in
1045         <tt>PATH</tt>.  Use this variable to override
1046         <tt>configure</tt>'s default behavior.</td>
1047   </tr>
1048   <tr>
1049     <td>CXX</td>
1050     <td>Tells <tt>configure</tt> which C++ compiler to use.  By default,
1051        <tt>configure</tt> will look for the first GCC C++ compiler in
1052        <tt>PATH</tt>.  Use this variable to override
1053        <tt>configure</tt>'s default behavior.</td>
1054   </tr>
1055 </table>
1056
1057 <p>The following options can be used to set or enable LLVM specific options:</p>
1058
1059 <dl>
1060   <dt><i>--with-llvmgccdir</i></dt>
1061   <dd>Path to the LLVM C/C++ FrontEnd to be used with this LLVM configuration.
1062   The value of this option should specify the full pathname of the C/C++ Front
1063   End to be used. If this option is not provided, the PATH will be searched for
1064   a program named <i>llvm-gcc</i> and the C/C++ FrontEnd install directory will
1065   be inferred from the path found. If the option is not given, and no llvm-gcc
1066   can be found in the path then a warning will be produced by
1067   <tt>configure</tt> indicating this situation. LLVM may still be built with
1068   the <tt>tools-only</tt> target but attempting to build the runtime libraries
1069   will fail as these libraries require llvm-gcc and llvm-g++. See
1070   <a href="#installcf">Install the GCC Front End</a> for details on installing
1071   the C/C++ Front End. See
1072   <a href="GCCFEBuildInstrs.html">Bootstrapping the LLVM C/C++ Front-End</a>
1073   for details on building the C/C++ Front End.</dd>
1074   <dt><i>--with-tclinclude</i></dt>
1075   <dd>Path to the tcl include directory under which <tt>tclsh</tt> can be
1076   found. Use this if you have multiple tcl installations on your machine and you
1077   want to use a specific one (8.x) for LLVM. LLVM only uses tcl for running the
1078   dejagnu based test suite in <tt>llvm/test</tt>. If you don't specify this
1079   option, the LLVM configure script will search for the tcl 8.4 and 8.3
1080   releases.
1081   <br><br>
1082   </dd>
1083   <dt><i>--enable-optimized</i></dt>
1084   <dd>
1085     Enables optimized compilation (debugging symbols are removed
1086     and GCC optimization flags are enabled). Note that this is the default
1087     setting     if you are using the LLVM distribution. The default behavior
1088     of an Subversion checkout is to use an unoptimized build (also known as a
1089     debug build).
1090     <br><br>
1091   </dd>
1092   <dt><i>--enable-debug-runtime</i></dt>
1093   <dd>
1094     Enables debug symbols in the runtime libraries. The default is to strip
1095     debug symbols from the runtime libraries.
1096   </dd>
1097   <dt><i>--enable-jit</i></dt>
1098   <dd>
1099     Compile the Just In Time (JIT) compiler functionality.  This is not
1100     available
1101     on all platforms.  The default is dependent on platform, so it is best
1102     to explicitly enable it if you want it.
1103     <br><br>
1104   </dd>
1105   <dt><i>--enable-targets=</i><tt>target-option</tt></dt>
1106   <dd>Controls which targets will be built and linked into llc. The default
1107   value for <tt>target_options</tt> is "all" which builds and links all
1108   available targets.  The value "host-only" can be specified to build only a
1109   native compiler (no cross-compiler targets available). The "native" target is
1110   selected as the target of the build host. You can also specify a comma
1111   separated list of target names that you want available in llc. The target
1112   names use all lower case. The current set of targets is: <br>
1113   <tt>alpha, ia64, powerpc, skeleton, sparc, x86</tt>.
1114   <br><br></dd>
1115   <dt><i>--enable-doxygen</i></dt>
1116   <dd>Look for the doxygen program and enable construction of doxygen based
1117   documentation from the source code. This is disabled by default because
1118   generating the documentation can take a long time and producess 100s of
1119   megabytes of output.</dd>
1120   <dt><i>--with-udis86</i></dt>
1121   <dd>LLVM can use external disassembler library for various purposes (now it's
1122   used only for examining code produced by JIT). This option will enable usage
1123   of <a href="http://udis86.sourceforge.net/">udis86</a> x86 (both 32 and 64
1124   bits) disassembler library.</dd>
1125 </dl>
1126
1127 <p>To configure LLVM, follow these steps:</p>
1128
1129 <ol>
1130     <li><p>Change directory into the object root directory:</p>
1131
1132     <div class="doc_code"><pre>% cd <i>OBJ_ROOT</i></pre></div></li>
1133
1134     <li><p>Run the <tt>configure</tt> script located in the LLVM source
1135     tree:</p>
1136
1137     <div class="doc_code">
1138     <pre>% <i>SRC_ROOT</i>/configure --prefix=/install/path [other options]</pre>
1139     </div></li>
1140 </ol>
1141
1142 </div>
1143
1144 <!-- ======================================================================= -->
1145 <h3>
1146   <a name="compile">Compiling the LLVM Suite Source Code</a>
1147 </h3>
1148
1149 <div>
1150
1151 <p>Once you have configured LLVM, you can build it.  There are three types of
1152 builds:</p>
1153
1154 <dl>
1155     <dt>Debug Builds
1156     <dd>
1157     These builds are the default when one is using an Subversion checkout and
1158     types <tt>gmake</tt> (unless the <tt>--enable-optimized</tt> option was
1159     used during configuration).  The build system will compile the tools and
1160     libraries with debugging information.  To get a Debug Build using the
1161     LLVM distribution the <tt>--disable-optimized</tt> option must be passed
1162     to <tt>configure</tt>.
1163     <br><br>
1164
1165     <dt>Release (Optimized) Builds
1166     <dd>
1167     These builds are enabled with the <tt>--enable-optimized</tt> option to
1168     <tt>configure</tt> or by specifying <tt>ENABLE_OPTIMIZED=1</tt> on the
1169     <tt>gmake</tt> command line.  For these builds, the build system will
1170     compile the tools and libraries with GCC optimizations enabled and strip
1171     debugging information from the libraries and executables it generates.
1172     Note that Release Builds are default when using an LLVM distribution.
1173     <br><br>
1174
1175     <dt>Profile Builds
1176     <dd>
1177     These builds are for use with profiling.  They compile profiling
1178     information into the code for use with programs like <tt>gprof</tt>.
1179     Profile builds must be started by specifying <tt>ENABLE_PROFILING=1</tt>
1180     on the <tt>gmake</tt> command line.
1181 </dl>
1182
1183 <p>Once you have LLVM configured, you can build it by entering the
1184 <i>OBJ_ROOT</i> directory and issuing the following command:</p>
1185
1186 <div class="doc_code"><pre>% gmake</pre></div>
1187
1188 <p>If the build fails, please <a href="#brokengcc">check here</a> to see if you
1189 are using a version of GCC that is known not to compile LLVM.</p>
1190
1191 <p>
1192 If you have multiple processors in your machine, you may wish to use some of
1193 the parallel build options provided by GNU Make.  For example, you could use the
1194 command:</p>
1195
1196 <div class="doc_code"><pre>% gmake -j2</pre></div>
1197
1198 <p>There are several special targets which are useful when working with the LLVM
1199 source code:</p>
1200
1201 <dl>
1202   <dt><tt>gmake clean</tt>
1203   <dd>
1204   Removes all files generated by the build.  This includes object files,
1205   generated C/C++ files, libraries, and executables.
1206   <br><br>
1207
1208   <dt><tt>gmake dist-clean</tt>
1209   <dd>
1210   Removes everything that <tt>gmake clean</tt> does, but also removes files
1211   generated by <tt>configure</tt>.  It attempts to return the source tree to the
1212   original state in which it was shipped.
1213   <br><br>
1214
1215   <dt><tt>gmake install</tt>
1216   <dd>
1217   Installs LLVM header files, libraries, tools, and documentation in a
1218   hierarchy
1219   under $PREFIX, specified with <tt>./configure --prefix=[dir]</tt>, which
1220   defaults to <tt>/usr/local</tt>.
1221   <br><br>
1222
1223   <dt><tt>gmake -C runtime install-bytecode</tt>
1224   <dd>
1225   Assuming you built LLVM into $OBJDIR, when this command is run, it will
1226   install bitcode libraries into the GCC front end's bitcode library
1227   directory.  If you need to update your bitcode libraries,
1228   this is the target to use once you've built them.
1229   <br><br>
1230 </dl>
1231
1232 <p>Please see the <a href="MakefileGuide.html">Makefile Guide</a> for further
1233 details on these <tt>make</tt> targets and descriptions of other targets
1234 available.</p>
1235
1236 <p>It is also possible to override default values from <tt>configure</tt> by
1237 declaring variables on the command line.  The following are some examples:</p>
1238
1239 <dl>
1240   <dt><tt>gmake ENABLE_OPTIMIZED=1</tt>
1241   <dd>
1242   Perform a Release (Optimized) build.
1243   <br><br>
1244
1245   <dt><tt>gmake ENABLE_OPTIMIZED=1 DISABLE_ASSERTIONS=1</tt>
1246   <dd>
1247   Perform a Release (Optimized) build without assertions enabled.
1248   <br><br>
1249
1250   <dt><tt>gmake ENABLE_OPTIMIZED=0</tt>
1251   <dd>
1252   Perform a Debug build.
1253   <br><br>
1254
1255   <dt><tt>gmake ENABLE_PROFILING=1</tt>
1256   <dd>
1257   Perform a Profiling build.
1258   <br><br>
1259
1260   <dt><tt>gmake VERBOSE=1</tt>
1261   <dd>
1262   Print what <tt>gmake</tt> is doing on standard output.
1263   <br><br>
1264
1265   <dt><tt>gmake TOOL_VERBOSE=1</tt></dt>
1266   <dd>Ask each tool invoked by the makefiles to print out what it is doing on
1267   the standard output. This also implies <tt>VERBOSE=1</tt>.
1268   <br><br></dd>
1269 </dl>
1270
1271 <p>Every directory in the LLVM object tree includes a <tt>Makefile</tt> to build
1272 it and any subdirectories that it contains.  Entering any directory inside the
1273 LLVM object tree and typing <tt>gmake</tt> should rebuild anything in or below
1274 that directory that is out of date.</p>
1275
1276 </div>
1277
1278 <!-- ======================================================================= -->
1279 <h3>
1280   <a name="cross-compile">Cross-Compiling LLVM</a>
1281 </h3>
1282
1283 <div>
1284   <p>It is possible to cross-compile LLVM itself. That is, you can create LLVM
1285   executables and libraries to be hosted on a platform different from the
1286   platform where they are build (a Canadian Cross build). To configure a
1287   cross-compile, supply the configure script with <tt>--build</tt> and
1288   <tt>--host</tt> options that are different. The values of these options must
1289   be legal target triples that your GCC compiler supports.</p>
1290
1291   <p>The result of such a build is executables that are not runnable on
1292   on the build host (--build option) but can be executed on the compile host
1293   (--host option).</p>
1294 </div>
1295
1296 <!-- ======================================================================= -->
1297 <h3>
1298   <a name="objfiles">The Location of LLVM Object Files</a>
1299 </h3>
1300
1301 <div>
1302
1303 <p>The LLVM build system is capable of sharing a single LLVM source tree among
1304 several LLVM builds.  Hence, it is possible to build LLVM for several different
1305 platforms or configurations using the same source tree.</p>
1306
1307 <p>This is accomplished in the typical autoconf manner:</p>
1308
1309 <ul>
1310   <li><p>Change directory to where the LLVM object files should live:</p>
1311
1312       <div class="doc_code"><pre>% cd <i>OBJ_ROOT</i></pre></div></li>
1313
1314   <li><p>Run the <tt>configure</tt> script found in the LLVM source
1315       directory:</p>
1316
1317       <div class="doc_code"><pre>% <i>SRC_ROOT</i>/configure</pre></div></li>
1318 </ul>
1319
1320 <p>The LLVM build will place files underneath <i>OBJ_ROOT</i> in directories
1321 named after the build type:</p>
1322
1323 <dl>
1324   <dt>Debug Builds with assertions enabled (the default)
1325   <dd>
1326   <dl>
1327     <dt>Tools
1328     <dd><tt><i>OBJ_ROOT</i>/Debug+Asserts/bin</tt>
1329     <dt>Libraries
1330     <dd><tt><i>OBJ_ROOT</i>/Debug+Asserts/lib</tt>
1331   </dl>
1332   <br><br>
1333
1334   <dt>Release Builds
1335   <dd>
1336   <dl>
1337     <dt>Tools
1338     <dd><tt><i>OBJ_ROOT</i>/Release/bin</tt>
1339     <dt>Libraries
1340     <dd><tt><i>OBJ_ROOT</i>/Release/lib</tt>
1341   </dl>
1342   <br><br>
1343
1344   <dt>Profile Builds
1345   <dd>
1346   <dl>
1347     <dt>Tools
1348     <dd><tt><i>OBJ_ROOT</i>/Profile/bin</tt>
1349     <dt>Libraries
1350     <dd><tt><i>OBJ_ROOT</i>/Profile/lib</tt>
1351   </dl>
1352 </dl>
1353
1354 </div>
1355
1356 <!-- ======================================================================= -->
1357 <h3>
1358   <a name="optionalconfig">Optional Configuration Items</a>
1359 </h3>
1360
1361 <div>
1362
1363 <p>
1364 If you're running on a Linux system that supports the "<a
1365 href="http://www.tat.physik.uni-tuebingen.de/~rguenth/linux/binfmt_misc.html">binfmt_misc</a>"
1366 module, and you have root access on the system, you can set your system up to
1367 execute LLVM bitcode files directly. To do this, use commands like this (the
1368 first command may not be required if you are already using the module):</p>
1369
1370 <div class="doc_code">
1371 <pre>
1372 $ mount -t binfmt_misc none /proc/sys/fs/binfmt_misc
1373 $ echo ':llvm:M::BC::/path/to/lli:' &gt; /proc/sys/fs/binfmt_misc/register
1374 $ chmod u+x hello.bc   (if needed)
1375 $ ./hello.bc
1376 </pre>
1377 </div>
1378
1379 <p>
1380 This allows you to execute LLVM bitcode files directly.  On Debian, you
1381 can also use this command instead of the 'echo' command above:
1382 </p>
1383
1384 <div class="doc_code">
1385 <pre>
1386 $ sudo update-binfmts --install llvm /path/to/lli --magic 'BC'
1387 </pre>
1388 </div>
1389
1390 </div>
1391
1392 </div>
1393
1394 <!-- *********************************************************************** -->
1395 <h2>
1396   <a name="layout">Program Layout</a>
1397 </h2>
1398 <!-- *********************************************************************** -->
1399
1400 <div>
1401
1402 <p>One useful source of information about the LLVM source base is the LLVM <a
1403 href="http://www.doxygen.org/">doxygen</a> documentation available at <tt><a
1404 href="http://llvm.org/doxygen/">http://llvm.org/doxygen/</a></tt>.
1405 The following is a brief introduction to code layout:</p>
1406
1407 <!-- ======================================================================= -->
1408 <h3>
1409   <a name="examples"><tt>llvm/examples</tt></a>
1410 </h3>
1411
1412 <div>
1413   <p>This directory contains some simple examples of how to use the LLVM IR and
1414   JIT.</p>
1415 </div>
1416
1417 <!-- ======================================================================= -->
1418 <h3>
1419   <a name="include"><tt>llvm/include</tt></a>
1420 </h3>
1421
1422 <div>
1423
1424 <p>This directory contains public header files exported from the LLVM
1425 library. The three main subdirectories of this directory are:</p>
1426
1427 <dl>
1428   <dt><tt><b>llvm/include/llvm</b></tt></dt>
1429   <dd>This directory contains all of the LLVM specific header files.  This
1430   directory also has subdirectories for different portions of LLVM:
1431   <tt>Analysis</tt>, <tt>CodeGen</tt>, <tt>Target</tt>, <tt>Transforms</tt>,
1432   etc...</dd>
1433
1434   <dt><tt><b>llvm/include/llvm/Support</b></tt></dt>
1435   <dd>This directory contains generic support libraries that are provided with
1436   LLVM but not necessarily specific to LLVM. For example, some C++ STL utilities
1437   and a Command Line option processing library store their header files here.
1438   </dd>
1439
1440   <dt><tt><b>llvm/include/llvm/Config</b></tt></dt>
1441   <dd>This directory contains header files configured by the <tt>configure</tt>
1442   script.  They wrap "standard" UNIX and C header files.  Source code can
1443   include these header files which automatically take care of the conditional
1444   #includes that the <tt>configure</tt> script generates.</dd>
1445 </dl>
1446 </div>
1447
1448 <!-- ======================================================================= -->
1449 <h3>
1450   <a name="lib"><tt>llvm/lib</tt></a>
1451 </h3>
1452
1453 <div>
1454
1455 <p>This directory contains most of the source files of the LLVM system. In LLVM,
1456 almost all code exists in libraries, making it very easy to share code among the
1457 different <a href="#tools">tools</a>.</p>
1458
1459 <dl>
1460   <dt><tt><b>llvm/lib/VMCore/</b></tt></dt>
1461   <dd> This directory holds the core LLVM source files that implement core
1462   classes like Instruction and BasicBlock.</dd>
1463
1464   <dt><tt><b>llvm/lib/AsmParser/</b></tt></dt>
1465   <dd>This directory holds the source code for the LLVM assembly language parser
1466   library.</dd>
1467
1468   <dt><tt><b>llvm/lib/BitCode/</b></tt></dt>
1469   <dd>This directory holds code for reading and write LLVM bitcode.</dd>
1470
1471   <dt><tt><b>llvm/lib/Analysis/</b></tt><dd>This directory contains a variety of
1472   different program analyses, such as Dominator Information, Call Graphs,
1473   Induction Variables, Interval Identification, Natural Loop Identification,
1474   etc.</dd>
1475
1476   <dt><tt><b>llvm/lib/Transforms/</b></tt></dt>
1477   <dd> This directory contains the source code for the LLVM to LLVM program
1478   transformations, such as Aggressive Dead Code Elimination, Sparse Conditional
1479   Constant Propagation, Inlining, Loop Invariant Code Motion, Dead Global
1480   Elimination, and many others.</dd>
1481
1482   <dt><tt><b>llvm/lib/Target/</b></tt></dt>
1483   <dd> This directory contains files that describe various target architectures
1484   for code generation.  For example, the <tt>llvm/lib/Target/X86</tt>
1485   directory holds the X86 machine description while
1486   <tt>llvm/lib/Target/CBackend</tt> implements the LLVM-to-C converter.</dd>
1487
1488   <dt><tt><b>llvm/lib/CodeGen/</b></tt></dt>
1489   <dd> This directory contains the major parts of the code generator: Instruction
1490   Selector, Instruction Scheduling, and Register Allocation.</dd>
1491
1492   <dt><tt><b>llvm/lib/MC/</b></tt></dt>
1493   <dd>(FIXME: T.B.D.)</dd>
1494
1495   <!--FIXME: obsoleted -->
1496   <dt><tt><b>llvm/lib/Debugger/</b></tt></dt>
1497   <dd> This directory contains the source level debugger library that makes
1498   it possible to instrument LLVM programs so that a debugger could identify
1499   source code locations at which the program is executing.</dd>
1500
1501   <dt><tt><b>llvm/lib/ExecutionEngine/</b></tt></dt>
1502   <dd> This directory contains libraries for executing LLVM bitcode directly
1503   at runtime in both interpreted and JIT compiled fashions.</dd>
1504
1505   <dt><tt><b>llvm/lib/Support/</b></tt></dt>
1506   <dd> This directory contains the source code that corresponds to the header
1507   files located in <tt>llvm/include/ADT/</tt>
1508   and <tt>llvm/include/Support/</tt>.</dd>
1509 </dl>
1510
1511 </div>
1512
1513 <!-- ======================================================================= -->
1514 <h3>
1515   <a name="projects"><tt>llvm/projects</tt></a>
1516 </h3>
1517
1518 <div>
1519   <p>This directory contains projects that are not strictly part of LLVM but are
1520   shipped with LLVM. This is also the directory where you should create your own
1521   LLVM-based projects. See <tt>llvm/projects/sample</tt> for an example of how
1522   to set up your own project.</p>
1523 </div>
1524
1525 <!-- ======================================================================= -->
1526 <h3>
1527   <a name="runtime"><tt>llvm/runtime</tt></a>
1528 </h3>
1529
1530 <div>
1531
1532 <p>This directory contains libraries which are compiled into LLVM bitcode and
1533 used when linking programs with the GCC front end.  Most of these libraries are
1534 skeleton versions of real libraries; for example, libc is a stripped down
1535 version of glibc.</p>
1536
1537 <p>Unlike the rest of the LLVM suite, this directory needs the LLVM GCC front
1538 end to compile.</p>
1539
1540 </div>
1541
1542 <!-- ======================================================================= -->
1543 <h3>
1544   <a name="test"><tt>llvm/test</tt></a>
1545 </h3>
1546
1547 <div>
1548   <p>This directory contains feature and regression tests and other basic sanity
1549   checks on the LLVM infrastructure. These are intended to run quickly and cover
1550   a lot of territory without being exhaustive.</p>
1551 </div>
1552
1553 <!-- ======================================================================= -->
1554 <h3>
1555   <a name="test-suite"><tt>test-suite</tt></a>
1556 </h3>
1557
1558 <div>
1559   <p>This is not a directory in the normal llvm module; it is a separate
1560   Subversion
1561   module that must be checked out (usually to <tt>projects/test-suite</tt>).
1562   This
1563   module contains a comprehensive correctness, performance, and benchmarking
1564   test
1565   suite for LLVM. It is a separate Subversion module because not every LLVM
1566   user is
1567   interested in downloading or building such a comprehensive test suite. For
1568   further details on this test suite, please see the
1569   <a href="TestingGuide.html">Testing Guide</a> document.</p>
1570 </div>
1571
1572 <!-- ======================================================================= -->
1573 <h3>
1574   <a name="tools"><tt>llvm/tools</tt></a>
1575 </h3>
1576
1577 <div>
1578
1579 <p>The <b>tools</b> directory contains the executables built out of the
1580 libraries above, which form the main part of the user interface.  You can
1581 always get help for a tool by typing <tt>tool_name -help</tt>.  The
1582 following is a brief introduction to the most important tools.  More detailed
1583 information is in the <a href="CommandGuide/index.html">Command Guide</a>.</p>
1584
1585 <dl>
1586
1587   <dt><tt><b>bugpoint</b></tt></dt>
1588   <dd><tt>bugpoint</tt> is used to debug
1589   optimization passes or code generation backends by narrowing down the
1590   given test case to the minimum number of passes and/or instructions that
1591   still cause a problem, whether it is a crash or miscompilation. See <a
1592   href="HowToSubmitABug.html">HowToSubmitABug.html</a> for more information
1593   on using <tt>bugpoint</tt>.</dd>
1594
1595   <dt><tt><b>llvm-ar</b></tt></dt>
1596   <dd>The archiver produces an archive containing
1597   the given LLVM bitcode files, optionally with an index for faster
1598   lookup.</dd>
1599
1600   <dt><tt><b>llvm-as</b></tt></dt>
1601   <dd>The assembler transforms the human readable LLVM assembly to LLVM
1602   bitcode.</dd>
1603
1604   <dt><tt><b>llvm-dis</b></tt></dt>
1605   <dd>The disassembler transforms the LLVM bitcode to human readable
1606   LLVM assembly.</dd>
1607
1608   <dt><tt><b>llvm-ld</b></tt></dt>
1609   <dd><tt>llvm-ld</tt> is a general purpose and extensible linker for LLVM.
1610   It performs standard link time optimizations and allows optimization
1611   modules to be loaded and run so that language specific optimizations can
1612   be applied at link time.</dd>
1613
1614   <dt><tt><b>llvm-link</b></tt></dt>
1615   <dd><tt>llvm-link</tt>, not surprisingly, links multiple LLVM modules into
1616   a single program.</dd>
1617
1618   <dt><tt><b>lli</b></tt></dt>
1619   <dd><tt>lli</tt> is the LLVM interpreter, which
1620   can directly execute LLVM bitcode (although very slowly...). For architectures
1621   that support it (currently x86, Sparc, and PowerPC), by default, <tt>lli</tt>
1622   will function as a Just-In-Time compiler (if the functionality was compiled
1623   in), and will execute the code <i>much</i> faster than the interpreter.</dd>
1624
1625   <dt><tt><b>llc</b></tt></dt>
1626   <dd> <tt>llc</tt> is the LLVM backend compiler, which
1627   translates LLVM bitcode to a native code assembly file or to C code (with
1628   the -march=c option).</dd>
1629
1630   <dt><tt><b>llvm-gcc</b></tt></dt>
1631   <dd><tt>llvm-gcc</tt> is a GCC-based C frontend that has been retargeted to
1632   use LLVM as its backend instead of GCC's RTL backend. It can also emit LLVM
1633   bitcode or assembly (with the <tt>-emit-llvm</tt> option) instead of the
1634   usual machine code output.  It works just like any other GCC compiler,
1635   taking the typical <tt>-c, -S, -E, -o</tt> options that are typically used.
1636   Additionally, the the source code for <tt>llvm-gcc</tt> is available as a
1637   separate Subversion module.</dd>
1638
1639   <dt><tt><b>opt</b></tt></dt>
1640   <dd><tt>opt</tt> reads LLVM bitcode, applies a series of LLVM to LLVM
1641   transformations (which are specified on the command line), and then outputs
1642   the resultant bitcode.  The '<tt>opt -help</tt>' command is a good way to
1643   get a list of the program transformations available in LLVM.<br>
1644   <dd><tt>opt</tt> can also be used to run a specific analysis on an input
1645   LLVM bitcode file and print out the results.  It is primarily useful for
1646   debugging analyses, or familiarizing yourself with what an analysis does.</dd>
1647 </dl>
1648 </div>
1649
1650 <!-- ======================================================================= -->
1651 <h3>
1652   <a name="utils"><tt>llvm/utils</tt></a>
1653 </h3>
1654
1655 <div>
1656
1657 <p>This directory contains utilities for working with LLVM source code, and some
1658 of the utilities are actually required as part of the build process because they
1659 are code generators for parts of LLVM infrastructure.</p>
1660
1661 <dl>
1662   <dt><tt><b>codegen-diff</b></tt> <dd><tt>codegen-diff</tt> is a script
1663   that finds differences between code that LLC generates and code that LLI
1664   generates. This is a useful tool if you are debugging one of them,
1665   assuming that the other generates correct output. For the full user
1666   manual, run <tt>`perldoc codegen-diff'</tt>.<br><br>
1667
1668   <dt><tt><b>emacs/</b></tt> <dd>The <tt>emacs</tt> directory contains
1669   syntax-highlighting files which will work with Emacs and XEmacs editors,
1670   providing syntax highlighting support for LLVM assembly files and TableGen
1671   description files. For information on how to use the syntax files, consult
1672   the <tt>README</tt> file in that directory.<br><br>
1673
1674   <dt><tt><b>getsrcs.sh</b></tt> <dd>The <tt>getsrcs.sh</tt> script finds
1675   and outputs all non-generated source files, which is useful if one wishes
1676   to do a lot of development across directories and does not want to
1677   individually find each file. One way to use it is to run, for example:
1678   <tt>xemacs `utils/getsources.sh`</tt> from the top of your LLVM source
1679   tree.<br><br>
1680
1681   <dt><tt><b>llvmgrep</b></tt></dt>
1682   <dd>This little tool performs an "egrep -H -n" on each source file in LLVM and
1683   passes to it a regular expression provided on <tt>llvmgrep</tt>'s command
1684   line. This is a very efficient way of searching the source base for a
1685   particular regular expression.</dd>
1686
1687   <dt><tt><b>makellvm</b></tt> <dd>The <tt>makellvm</tt> script compiles all
1688   files in the current directory and then compiles and links the tool that
1689   is the first argument. For example, assuming you are in the directory
1690   <tt>llvm/lib/Target/Sparc</tt>, if <tt>makellvm</tt> is in your path,
1691   simply running <tt>makellvm llc</tt> will make a build of the current
1692   directory, switch to directory <tt>llvm/tools/llc</tt> and build it,
1693   causing a re-linking of LLC.<br><br>
1694
1695   <dt><tt><b>NewNightlyTest.pl</b></tt> and
1696   <tt><b>NightlyTestTemplate.html</b></tt> <dd>These files are used in a
1697   cron script to generate nightly status reports of the functionality of
1698   tools, and the results can be seen by following the appropriate link on
1699   the <a href="http://llvm.org/">LLVM homepage</a>.<br><br>
1700
1701   <dt><tt><b>TableGen/</b></tt> <dd>The <tt>TableGen</tt> directory contains
1702   the tool used to generate register descriptions, instruction set
1703   descriptions, and even assemblers from common TableGen description
1704   files.<br><br>
1705
1706   <dt><tt><b>vim/</b></tt> <dd>The <tt>vim</tt> directory contains
1707   syntax-highlighting files which will work with the VIM editor, providing
1708   syntax highlighting support for LLVM assembly files and TableGen
1709   description files. For information on how to use the syntax files, consult
1710   the <tt>README</tt> file in that directory.<br><br>
1711
1712 </dl>
1713
1714 </div>
1715
1716 </div>
1717
1718 <!-- *********************************************************************** -->
1719 <h2>
1720   <a name="tutorial">An Example Using the LLVM Tool Chain</a>
1721 </h2>
1722 <!-- *********************************************************************** -->
1723
1724 <div>
1725 <p>This section gives an example of using LLVM.  llvm-gcc3 is now obsolete,
1726 so we only include instructions for llvm-gcc4.
1727 </p>
1728
1729 <p><b>Note:</b> The <i>gcc4</i> frontend's invocation is <b><i>considerably different</i></b>
1730 from the previous <i>gcc3</i> frontend. In particular, the <i>gcc4</i> frontend <b><i>does not</i></b>
1731 create bitcode by default: <i>gcc4</i> produces native code. As the example below illustrates,
1732 the '--emit-llvm' flag is needed to produce LLVM bitcode output. For <i>makefiles</i> and
1733 <i>configure</i> scripts, the CFLAGS variable needs '--emit-llvm' to produce bitcode
1734 output.</p>
1735
1736 <!-- ======================================================================= -->
1737 <h3>
1738   <a name="tutorial4">Example with llvm-gcc4</a>
1739 </h3>
1740
1741 <div>
1742
1743 <ol>
1744   <li><p>First, create a simple C file, name it 'hello.c':</p>
1745
1746 <div class="doc_code">
1747 <pre>
1748 #include &lt;stdio.h&gt;
1749
1750 int main() {
1751   printf("hello world\n");
1752   return 0;
1753 }
1754 </pre></div></li>
1755
1756   <li><p>Next, compile the C file into a native executable:</p>
1757
1758       <div class="doc_code"><pre>% llvm-gcc hello.c -o hello</pre></div>
1759
1760       <p>Note that llvm-gcc works just like GCC by default.  The standard -S and
1761         -c arguments work as usual (producing a native .s or .o file,
1762         respectively).</p></li>
1763
1764   <li><p>Next, compile the C file into a LLVM bitcode file:</p>
1765
1766       <div class="doc_code">
1767       <pre>% llvm-gcc -O3 -emit-llvm hello.c -c -o hello.bc</pre></div>
1768
1769       <p>The -emit-llvm option can be used with the -S or -c options to emit an
1770          LLVM ".ll" or ".bc" file (respectively) for the code.  This allows you
1771          to use the <a href="CommandGuide/index.html">standard LLVM tools</a> on
1772          the bitcode file.</p>
1773
1774       <p>Unlike llvm-gcc3, llvm-gcc4 correctly responds to -O[0123] arguments.
1775          </p></li>
1776
1777   <li><p>Run the program in both forms. To run the program, use:</p>
1778
1779       <div class="doc_code"><pre>% ./hello</pre></div>
1780
1781       <p>and</p>
1782
1783       <div class="doc_code"><pre>% lli hello.bc</pre></div>
1784
1785       <p>The second examples shows how to invoke the LLVM JIT, <a
1786        href="CommandGuide/html/lli.html">lli</a>.</p></li>
1787
1788   <li><p>Use the <tt>llvm-dis</tt> utility to take a look at the LLVM assembly
1789       code:</p>
1790
1791 <div class="doc_code">
1792 <pre>llvm-dis &lt; hello.bc | less</pre>
1793 </div></li>
1794
1795   <li><p>Compile the program to native assembly using the LLC code
1796       generator:</p>
1797
1798       <div class="doc_code"><pre>% llc hello.bc -o hello.s</pre></div></li>
1799
1800   <li><p>Assemble the native assembly language file into a program:</p>
1801
1802 <div class="doc_code">
1803 <pre>
1804 <b>Solaris:</b> % /opt/SUNWspro/bin/cc -xarch=v9 hello.s -o hello.native
1805
1806 <b>Others:</b>  % gcc hello.s -o hello.native
1807 </pre>
1808 </div></li>
1809
1810   <li><p>Execute the native code program:</p>
1811
1812       <div class="doc_code"><pre>% ./hello.native</pre></div>
1813
1814       <p>Note that using llvm-gcc to compile directly to native code (i.e. when
1815          the -emit-llvm option is not present) does steps 6/7/8 for you.</p>
1816         </li>
1817
1818 </ol>
1819
1820 </div>
1821
1822 </div>
1823
1824 <!-- *********************************************************************** -->
1825 <h2>
1826   <a name="problems">Common Problems</a>
1827 </h2>
1828 <!-- *********************************************************************** -->
1829
1830 <div>
1831
1832 <p>If you are having problems building or using LLVM, or if you have any other
1833 general questions about LLVM, please consult the <a href="FAQ.html">Frequently
1834 Asked Questions</a> page.</p>
1835
1836 </div>
1837
1838 <!-- *********************************************************************** -->
1839 <h2>
1840   <a name="links">Links</a>
1841 </h2>
1842 <!-- *********************************************************************** -->
1843
1844 <div>
1845
1846 <p>This document is just an <b>introduction</b> on how to use LLVM to do
1847 some simple things... there are many more interesting and complicated things
1848 that you can do that aren't documented here (but we'll gladly accept a patch
1849 if you want to write something up!).  For more information about LLVM, check
1850 out:</p>
1851
1852 <ul>
1853   <li><a href="http://llvm.org/">LLVM homepage</a></li>
1854   <li><a href="http://llvm.org/doxygen/">LLVM doxygen tree</a></li>
1855   <li><a href="http://llvm.org/docs/Projects.html">Starting a Project
1856   that Uses LLVM</a></li>
1857 </ul>
1858
1859 </div>
1860
1861 <!-- *********************************************************************** -->
1862
1863 <hr>
1864 <address>
1865   <a href="http://jigsaw.w3.org/css-validator/check/referer"><img
1866   src="http://jigsaw.w3.org/css-validator/images/vcss-blue" alt="Valid CSS"></a>
1867   <a href="http://validator.w3.org/check/referer"><img
1868   src="http://www.w3.org/Icons/valid-html401-blue" alt="Valid HTML 4.01"></a>
1869
1870   <a href="mailto:sabre@nondot.org">Chris Lattner</a><br>
1871   <a href="http://llvm.x10sys.com/rspencer/">Reid Spencer</a><br>
1872   <a href="http://llvm.org/">The LLVM Compiler Infrastructure</a><br>
1873   Last modified: $Date$
1874 </address>
1875 </body>
1876 </html>