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