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