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 81basic information.</p> 82 83<p>First, LLVM comes in three pieces. The first piece is the LLVM 84suite. This contains all of the tools, libraries, and header files 85needed to use the low level virtual machine. It contains an 86assembler, disassembler, bitcode analyzer and bitcode optimizer. It 87also contains basic regression tests that can be used to test the LLVM 88tools and the GCC front end.</p> 89 90<p>The second piece is the GCC front end. This component provides a version of 91GCC that compiles C and C++ code into LLVM bitcode. Currently, the GCC front 92end uses the GCC parser to convert code to LLVM. Once 93compiled into LLVM bitcode, a program can be manipulated with the LLVM tools 94from the LLVM suite.</p> 95 96<p> 97There is a third, optional piece called Test Suite. It is a suite of programs 98with a testing harness that can be used to further test LLVM's functionality 99and 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 |& tee gnumake.out 178 # 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 186detailed information on configuring and compiling LLVM. See <a 187href="#environment">Setting Up Your Environment</a> for tips that simplify 188working with the GCC front end and LLVM tools. Go to <a href="#layout">Program 189Layout</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. 202This may save you some trouble by knowing ahead of time what hardware and 203software 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 325up</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>"--enable-shared"</i>.</a></li> 346<li><a name="pf_12">To compile SPU backend, you need to add 347 <tt>"LDFLAGS=-Wl,--stack,16777216"</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 352mode, depending on the system (it is so large because of all the debugging 353information and the fact that the libraries are statically linked into multiple 354tools). If you do not need many of the tools and you are space-conscious, you 355can pass <tt>ONLY_TOOLS="tools you need"</tt> to make. The Release build 356requires considerably less space.</p> 357 358<p>The LLVM suite <i>may</i> compile on other platforms, but it is not 359guaranteed to do so. If compilation is successful, the LLVM utilities should be 360able to assemble, disassemble, analyze, and optimize LLVM bitcode. Code 361generation should work as well, although the generated native code may not work 362on your platform.</p> 363 364<p>The GCC front end is not very portable at the moment. If you want to get it 365to work on another platform, you can download a copy of the source and <a 366href="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>≥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>≥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.61</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.10</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.61), and consequently, GNU M4 (version 1.4 475 or higher). You will also need automake (1.10). 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 518bugs in the compiler. In particular, several versions of GCC crash when trying 519to compile LLVM. We routinely use GCC 3.3.3, 3.4.0, and Apple 4.0.1 520successfully with them (however, see important notes below). Other versions 521of GCC will probably work as well. GCC versions listed 522here are known to not work. If you are using one of these versions, please try 523to upgrade your GCC to something more recent. If you run into a problem with a 524version of GCC not listed here, please <a href="mailto:llvmdev@cs.uiuc.edu">let 525us know</a>. Please use the "<tt>gcc -v</tt>" command to find out which version 526of GCC you are using. 527</p> 528 529<p><b>GCC versions prior to 3.0</b>: GCC 2.96.x and before had several 530problems in the STL that effectively prevent it from compiling LLVM. 531</p> 532 533<p><b>GCC 3.2.2 and 3.2.3</b>: These versions of GCC fails to compile LLVM with 534a bogus template error. This was fixed in later GCCs.</p> 535 536<p><b>GCC 3.3.2</b>: This version of GCC suffered from a <a 537href="http://gcc.gnu.org/PR13392">serious bug</a> which causes it to crash in 538the "<tt>convert_from_eh_region_ranges_1</tt>" GCC function.</p> 539 540<p><b>Cygwin GCC 3.3.3</b>: The version of GCC 3.3.3 commonly shipped with 541 Cygwin does not work. Please <a href="GCCFEBuildInstrs.html#cygwin">upgrade 542 to a newer version</a> if possible.</p> 543<p><b>SuSE GCC 3.3.3</b>: The version of GCC 3.3.3 shipped with SuSE 9.1 (and 544 possibly others) does not compile LLVM correctly (it appears that exception 545 handling is broken in some cases). Please download the FSF 3.3.3 or upgrade 546 to a newer version of GCC.</p> 547<p><b>GCC 3.4.0 on linux/x86 (32-bit)</b>: GCC miscompiles portions of the 548 code generator, causing an infinite loop in the llvm-gcc build when built 549 with optimizations enabled (i.e. a release build).</p> 550<p><b>GCC 3.4.2 on linux/x86 (32-bit)</b>: GCC miscompiles portions of the 551 code generator at -O3, as with 3.4.0. However gcc 3.4.2 (unlike 3.4.0) 552 correctly compiles LLVM at -O2. A work around is to build release LLVM 553 builds with "make ENABLE_OPTIMIZED=1 OPTIMIZE_OPTION=-O2 ..."</p> 554<p><b>GCC 3.4.x on X86-64/amd64</b>: GCC <a href="http://llvm.org/PR1056"> 555 miscompiles portions of LLVM</a>.</p> 556<p><b>GCC 3.4.4 (CodeSourcery ARM 2005q3-2)</b>: this compiler miscompiles LLVM 557 when building with optimizations enabled. It appears to work with 558 "<tt>make ENABLE_OPTIMIZED=1 OPTIMIZE_OPTION=-O1</tt>" or build a debug 559 build.</p> 560<p><b>IA-64 GCC 4.0.0</b>: The IA-64 version of GCC 4.0.0 is known to 561 miscompile LLVM.</p> 562<p><b>Apple Xcode 2.3</b>: GCC crashes when compiling LLVM at -O3 (which is the 563 default with ENABLE_OPTIMIZED=1. To work around this, build with 564 "ENABLE_OPTIMIZED=1 OPTIMIZE_OPTION=-O2".</p> 565<p><b>GCC 4.1.1</b>: GCC fails to build LLVM with template concept check errors 566 compiling some files. At the time of this writing, GCC mainline (4.2) 567 did not share the problem.</p> 568<p><b>GCC 4.1.1 on X86-64/amd64</b>: GCC <a href="http://llvm.org/PR1063"> 569 miscompiles portions of LLVM</a> when compiling llvm itself into 64-bit 570 code. LLVM will appear to mostly work but will be buggy, e.g. failing 571 portions of its testsuite.</p> 572<p><b>GCC 4.1.2 on OpenSUSE</b>: Seg faults during libstdc++ build and on x86_64 573platforms compiling md5.c gets a mangled constant.</p> 574<p><b>GCC 4.1.2 (20061115 (prerelease) (Debian 4.1.1-21)) on Debian</b>: Appears 575to miscompile parts of LLVM 2.4. One symptom is ValueSymbolTable complaining 576about symbols remaining in the table on destruction.</p> 577<p><b>GCC 4.1.2 20071124 (Red Hat 4.1.2-42)</b>: Suffers from the same symptoms 578as the previous one. It appears to work with ENABLE_OPTIMIZED=0 (the default).</p> 579<p><b>Cygwin GCC 4.3.2 20080827 (beta) 2</b>: 580 Users <a href="http://llvm.org/PR4145">reported</a> various problems related 581 with link errors when using this GCC version.</p> 582<p><b>Debian GCC 4.3.2 on X86</b>: Crashes building some files in LLVM 2.6.</p> 583<p><b>GCC 4.3.3 (Debian 4.3.3-10) on ARM</b>: Miscompiles parts of LLVM 2.6 584when optimizations are turned on. The symptom is an infinite loop in 585FoldingSetImpl::RemoveNode while running the code generator.</p> 586<p><b>GCC 4.3.5 and GCC 4.4.5 on ARM</b>: These can miscompile <tt>value >> 5871</tt> even at -O0. A test failure in <tt>test/Assembler/alignstack.ll</tt> is 588one symptom of the problem. 589<p><b>GNU ld 2.16.X</b>. Some 2.16.X versions of the ld linker will produce very 590long warning messages complaining that some ".gnu.linkonce.t.*" symbol was 591defined in a discarded section. You can safely ignore these messages as they are 592erroneous and the linkage is correct. These messages disappear using ld 5932.17.</p> 594 595<p><b>GNU binutils 2.17</b>: Binutils 2.17 contains <a 596href="http://sourceware.org/bugzilla/show_bug.cgi?id=3111">a bug</a> which 597causes huge link times (minutes instead of seconds) when building LLVM. We 598recommend upgrading to a newer version (2.17.50.0.4 or later).</p> 599 600<p><b>GNU Binutils 2.19.1 Gold</b>: This version of Gold contained 601<a href="http://sourceware.org/bugzilla/show_bug.cgi?id=9836">a bug</a> 602which causes intermittent failures when building LLVM with position independent 603code. The symptom is an error about cyclic dependencies. We recommend 604upgrading to a newer version of Gold.</p> 605 606</div> 607 608</div> 609 610<!-- *********************************************************************** --> 611<h2> 612 <a name="starting">Getting Started with LLVM</a> 613</h2> 614<!-- *********************************************************************** --> 615 616<div> 617 618<p>The remainder of this guide is meant to get you up and running with 619LLVM and to give you some basic information about the LLVM environment.</p> 620 621<p>The later sections of this guide describe the <a 622href="#layout">general layout</a> of the the LLVM source tree, a <a 623href="#tutorial">simple example</a> using the LLVM tool chain, and <a 624href="#links">links</a> to find more information about LLVM or to get 625help via e-mail.</p> 626 627<!-- ======================================================================= --> 628<h3> 629 <a name="terminology">Terminology and Notation</a> 630</h3> 631 632<div> 633 634<p>Throughout this manual, the following names are used to denote paths 635specific to the local system and working environment. <i>These are not 636environment variables you need to set but just strings used in the rest 637of this document below</i>. In any of the examples below, simply replace 638each of these names with the appropriate pathname on your local system. 639All these paths are absolute:</p> 640 641<dl> 642 <dt>SRC_ROOT 643 <dd> 644 This is the top level directory of the LLVM source tree. 645 <br><br> 646 647 <dt>OBJ_ROOT 648 <dd> 649 This is the top level directory of the LLVM object tree (i.e. the 650 tree where object files and compiled programs will be placed. It 651 can be the same as SRC_ROOT). 652 <br><br> 653 654 <dt>LLVMGCCDIR 655 <dd> 656 This is where the LLVM GCC Front End is installed. 657 <p> 658 For the pre-built GCC front end binaries, the LLVMGCCDIR is 659 <tt>llvm-gcc/<i>platform</i>/llvm-gcc</tt>. 660</dl> 661 662</div> 663 664<!-- ======================================================================= --> 665<h3> 666 <a name="environment">Setting Up Your Environment</a> 667</h3> 668 669<div> 670 671<p> 672In order to compile and use LLVM, you may need to set some environment 673variables. 674 675<dl> 676 <dt><tt>LLVM_LIB_SEARCH_PATH</tt>=<tt>/path/to/your/bitcode/libs</tt></dt> 677 <dd>[Optional] This environment variable helps LLVM linking tools find the 678 locations of your bitcode libraries. It is provided only as a 679 convenience since you can specify the paths using the -L options of the 680 tools and the C/C++ front-end will automatically use the bitcode files 681 installed in its 682 <tt>lib</tt> directory.</dd> 683</dl> 684 685</div> 686 687<!-- ======================================================================= --> 688<h3> 689 <a name="unpack">Unpacking the LLVM Archives</a> 690</h3> 691 692<div> 693 694<p> 695If you have the LLVM distribution, you will need to unpack it before you 696can begin to compile it. LLVM is distributed as a set of two files: the LLVM 697suite and the LLVM GCC front end compiled for your platform. There is an 698additional test suite that is optional. Each file is a TAR archive that is 699compressed with the gzip program. 700</p> 701 702<p>The files are as follows, with <em>x.y</em> marking the version number: 703<dl> 704 <dt><tt>llvm-x.y.tar.gz</tt></dt> 705 <dd>Source release for the LLVM libraries and tools.<br></dd> 706 707 <dt><tt>llvm-test-x.y.tar.gz</tt></dt> 708 <dd>Source release for the LLVM test-suite.</dd> 709 710 <dt><tt>llvm-gcc-4.2-x.y.source.tar.gz</tt></dt> 711 <dd>Source release of the llvm-gcc-4.2 front end. See README.LLVM in the root 712 directory for build instructions.<br></dd> 713 714 <dt><tt>llvm-gcc-4.2-x.y-platform.tar.gz</tt></dt> 715 <dd>Binary release of the llvm-gcc-4.2 front end for a specific platform.<br></dd> 716 717</dl> 718 719</div> 720 721<!-- ======================================================================= --> 722<h3> 723 <a name="checkout">Checkout LLVM from Subversion</a> 724</h3> 725 726<div> 727 728<p>If you have access to our Subversion repository, you can get a fresh copy of 729the entire source code. All you need to do is check it out from Subversion as 730follows:</p> 731 732<ul> 733 <li><tt>cd <i>where-you-want-llvm-to-live</i></tt></li> 734 <li>Read-Only: <tt>svn co http://llvm.org/svn/llvm-project/llvm/trunk llvm</tt></li> 735 <li>Read-Write:<tt>svn co https://user@llvm.org/svn/llvm-project/llvm/trunk 736 llvm</tt></li> 737</ul> 738 739 740<p>This will create an '<tt>llvm</tt>' directory in the current 741directory and fully populate it with the LLVM source code, Makefiles, 742test directories, and local copies of documentation files.</p> 743 744<p>If you want to get a specific release (as opposed to the most recent 745revision), you can checkout it from the '<tt>tags</tt>' directory (instead of 746'<tt>trunk</tt>'). The following releases are located in the following 747subdirectories of the '<tt>tags</tt>' directory:</p> 748 749<ul> 750<li>Release 3.0: <b>RELEASE_30/final</b></li> 751<li>Release 2.9: <b>RELEASE_29/final</b></li> 752<li>Release 2.8: <b>RELEASE_28</b></li> 753<li>Release 2.7: <b>RELEASE_27</b></li> 754<li>Release 2.6: <b>RELEASE_26</b></li> 755<li>Release 2.5: <b>RELEASE_25</b></li> 756<li>Release 2.4: <b>RELEASE_24</b></li> 757<li>Release 2.3: <b>RELEASE_23</b></li> 758<li>Release 2.2: <b>RELEASE_22</b></li> 759<li>Release 2.1: <b>RELEASE_21</b></li> 760<li>Release 2.0: <b>RELEASE_20</b></li> 761<li>Release 1.9: <b>RELEASE_19</b></li> 762<li>Release 1.8: <b>RELEASE_18</b></li> 763<li>Release 1.7: <b>RELEASE_17</b></li> 764<li>Release 1.6: <b>RELEASE_16</b></li> 765<li>Release 1.5: <b>RELEASE_15</b></li> 766<li>Release 1.4: <b>RELEASE_14</b></li> 767<li>Release 1.3: <b>RELEASE_13</b></li> 768<li>Release 1.2: <b>RELEASE_12</b></li> 769<li>Release 1.1: <b>RELEASE_11</b></li> 770<li>Release 1.0: <b>RELEASE_1</b></li> 771</ul> 772 773<p>If you would like to get the LLVM test suite (a separate package as of 1.4), 774you get it from the Subversion repository:</p> 775 776<div class="doc_code"> 777<pre> 778% cd llvm/projects 779% svn co http://llvm.org/svn/llvm-project/test-suite/trunk test-suite 780</pre> 781</div> 782 783<p>By placing it in the <tt>llvm/projects</tt>, it will be automatically 784configured by the LLVM configure script as well as automatically updated when 785you run <tt>svn update</tt>.</p> 786 787<p>If you would like to get the GCC front end source code, you can also get it 788and build it yourself. Please follow <a href="GCCFEBuildInstrs.html">these 789instructions</a> to successfully get and build the LLVM GCC front-end.</p> 790 791</div> 792 793<!-- ======================================================================= --> 794<h3> 795 <a name="git_mirror">GIT mirror</a> 796</h3> 797 798<div> 799 800<p>GIT mirrors are available for a number of LLVM subprojects. These mirrors 801 sync automatically with each Subversion commit and contain all necessary 802 git-svn marks (so, you can recreate git-svn metadata locally). Note that right 803 now mirrors reflect only <tt>trunk</tt> for each project. You can do the 804 read-only GIT clone of LLVM via:</p> 805 806<pre class="doc_code"> 807git clone http://llvm.org/git/llvm.git 808</pre> 809 810<p>If you want to check out clang too, run:</p> 811 812<pre class="doc_code"> 813git clone http://llvm.org/git/llvm.git 814cd llvm/tools 815git clone http://llvm.org/git/clang.git 816</pre> 817 818<p> 819Since the upstream repository is in Subversion, you should use 820<tt>"git pull --rebase"</tt> 821instead of <tt>"git pull"</tt> to avoid generating a non-linear 822history in your clone. 823To configure <tt>"git pull"</tt> to pass <tt>--rebase</tt> by default 824on the master branch, run the following command: 825</p> 826 827<pre class="doc_code"> 828git config branch.master.rebase true 829</pre> 830 831<h4>Sending patches with Git</h4> 832<div> 833<p> 834Please read <a href="DeveloperPolicy.html#patches">Developer Policy</a>, too. 835</p> 836 837<p> 838Assume <tt>master</tt> points the upstream and <tt>mybranch</tt> points your 839working branch, and <tt>mybranch</tt> is rebased onto <tt>master</tt>. 840At first you may check sanity of whitespaces: 841</p> 842 843<pre class="doc_code"> 844git diff --check master..mybranch 845</pre> 846 847<p> 848The easiest way to generate a patch is as below: 849</p> 850 851<pre class="doc_code"> 852git diff master..mybranch > /path/to/mybranch.diff 853</pre> 854 855<p> 856It is a little different from svn-generated diff. git-diff-generated diff has 857prefixes like <tt>a/</tt> and <tt>b/</tt>. Don't worry, most developers might 858know it could be accepted with <tt>patch -p1 -N</tt>. 859</p> 860 861<p> 862But you may generate patchset with git-format-patch. It generates 863by-each-commit patchset. To generate patch files to attach to your article: 864</p> 865 866<pre class="doc_code"> 867git format-patch --no-attach master..mybranch -o /path/to/your/patchset 868</pre> 869 870<p> 871If you would like to send patches directly, you may use git-send-email or 872git-imap-send. Here is an example to generate the patchset in Gmail's [Drafts]. 873</p> 874 875<pre class="doc_code"> 876git format-patch --attach master..mybranch --stdout | git imap-send 877</pre> 878 879<p> 880Then, your .git/config should have [imap] sections. 881</p> 882 883<pre class="doc_code"> 884[imap] 885 host = imaps://imap.gmail.com 886 user = <em>your.gmail.account</em>@gmail.com 887 pass = <em>himitsu!</em> 888 port = 993 889 sslverify = false 890; in English 891 folder = "[Gmail]/Drafts" 892; example for Japanese, "Modified UTF-7" encoded. 893 folder = "[Gmail]/&Tgtm+DBN-" 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"> 905git clone http://llvm.org/git/llvm.git 906cd llvm 907git svn init https://llvm.org/svn/llvm-project/llvm/trunk --username=<username> 908git config svn-remote.svn.fetch :refs/remotes/origin/master 909git svn rebase -l # -l avoids fetching ahead of the git mirror. 910 911# If you have clang too: 912cd tools 913git clone http://llvm.org/git/clang.git 914cd clang 915git svn init https://llvm.org/svn/llvm-project/cfe/trunk --username=<username> 916git config svn-remote.svn.fetch :refs/remotes/origin/master 917git svn rebase -l 918</pre> 919 920<p>To update this clone without generating git-svn tags that conflict 921with the upstream git repo, run:</p> 922 923<pre class="doc_code"> 924git fetch && (cd tools/clang && git fetch) # Get matching revisions of both trees. 925git checkout master 926git 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 933you'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 935intended for relative newbies to git. If you have more experience, 936you can likely improve on it.)</p> 937 938<p>The git-svn metadata can get out of sync after you mess around with 939branches and <code>dcommit</code>. When that happens, <code>git svn 940dcommit</code> stops working, complaining about files with uncommitted 941changes. The fix is to rebuild the metadata:</p> 942 943<pre class="doc_code"> 944rm -rf .git/svn 945git 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 960GCC front end) you can optionally extract the front end from the binary distribution. 961It is used for running the LLVM test-suite and for compiling C/C++ programs. Note that 962you can optionally <a href="GCCFEBuildInstrs.html">build llvm-gcc yourself</a> after building the 963main LLVM repository.</p> 964 965<p>To install the GCC front end, do the following (on Windows, use an archival tool 966like <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 976Windows-based system, add the <tt>bin</tt> subdirectory of your front end installation directory 977to 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 981automatically detect <tt>llvm-gcc</tt>'s presence (if it is in your path) enabling its 982use in test-suite. Note that you can always build or install <tt>llvm-gcc</tt> at any 983point after building the main LLVM repository: just reconfigure llvm and 984test-suite will pick it up. 985</p> 986 987<p>As a convenience for Windows users, the front end binaries for MinGW/x86 include 988versions of the required w32api and mingw-runtime binaries. The last remaining step for 989Windows 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 991front end installation steps are not quite the same as a typical manual MinGW installation, 992they 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 1003example, the binary distribution may include an old version of a system header 1004file, not "fix" a header file that needs to be fixed for GCC, or it may be linked with 1005libraries 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, 1007this 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 1010newer versions of the w32api and mingw-runtime binary packages that may become available 1011from MinGW. At this time, it's best to think of the MinGW LLVM GCC front end binary as 1012a self-contained convenience package that requires Windows users to simply download and 1013uncompress 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 1016binaries is not as easy as previously described, or you would like to suggest improvements, 1017please 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 1031configured via the <tt>configure</tt> script. This script sets variables in the 1032various <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 1034the Makefiles needed to begin building LLVM.</p> 1035 1036<p>The following environment variables are used by the <tt>configure</tt> 1037script 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 1152builds:</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 1189are using a version of GCC that is known not to compile LLVM.</p> 1190 1191<p> 1192If you have multiple processors in your machine, you may wish to use some of 1193the parallel build options provided by GNU Make. For example, you could use the 1194command:</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 1199source 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 1233details on these <tt>make</tt> targets and descriptions of other targets 1234available.</p> 1235 1236<p>It is also possible to override default values from <tt>configure</tt> by 1237declaring 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 1272it and any subdirectories that it contains. Entering any directory inside the 1273LLVM object tree and typing <tt>gmake</tt> should rebuild anything in or below 1274that 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 1304several LLVM builds. Hence, it is possible to build LLVM for several different 1305platforms 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 1321named 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> 1364If you're running on a Linux system that supports the "<a 1365href="http://www.tat.physik.uni-tuebingen.de/~rguenth/linux/binfmt_misc.html">binfmt_misc</a>" 1366module, and you have root access on the system, you can set your system up to 1367execute LLVM bitcode files directly. To do this, use commands like this (the 1368first 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:' > /proc/sys/fs/binfmt_misc/register 1374$ chmod u+x hello.bc (if needed) 1375$ ./hello.bc 1376</pre> 1377</div> 1378 1379<p> 1380This allows you to execute LLVM bitcode files directly. On Debian, you 1381can 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 1403href="http://www.doxygen.org/">doxygen</a> documentation available at <tt><a 1404href="http://llvm.org/doxygen/">http://llvm.org/doxygen/</a></tt>. 1405The 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 1425library. 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, 1456almost all code exists in libraries, making it very easy to share code among the 1457different <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 1533used when linking programs with the GCC front end. Most of these libraries are 1534skeleton versions of real libraries; for example, libc is a stripped down 1535version of glibc.</p> 1536 1537<p>Unlike the rest of the LLVM suite, this directory needs the LLVM GCC front 1538end 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 1580libraries above, which form the main part of the user interface. You can 1581always get help for a tool by typing <tt>tool_name -help</tt>. The 1582following is a brief introduction to the most important tools. More detailed 1583information 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 1658of the utilities are actually required as part of the build process because they 1659are 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, 1726so 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> 1730from the previous <i>gcc3</i> frontend. In particular, the <i>gcc4</i> frontend <b><i>does not</i></b> 1731create bitcode by default: <i>gcc4</i> produces native code. As the example below illustrates, 1732the '--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 1734output.</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 <stdio.h> 1749 1750int 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 < 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 1833general questions about LLVM, please consult the <a href="FAQ.html">Frequently 1834Asked 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 1847some simple things... there are many more interesting and complicated things 1848that you can do that aren't documented here (but we'll gladly accept a patch 1849if you want to write something up!). For more information about LLVM, check 1850out:</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: 2011-10-17 02:31:32 -0400 (Mon, 17 Oct 2011) $ 1874</address> 1875</body> 1876</html> 1877