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 class="doc_code"> 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 class="doc_code"> 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> 818 Since the upstream repository is in Subversion, you should use 819 <tt>"git pull --rebase"</tt> 820 instead of <tt>"git pull"</tt> to avoid generating a non-linear 821 history in your clone. 822 To configure <tt>"git pull"</tt> to pass <tt>--rebase</tt> by default 823 on the master branch, run the following command: 824 </p> 825 826 <pre class="doc_code"> 827 git config branch.master.rebase true 828 </pre> 829 830 <h4>Sending patches with Git</h4> 831 <div> 832 <p> 833 Please read <a href="DeveloperPolicy.html#patches">Developer Policy</a>, too. 834 </p> 835 836 <p> 837 Assume <tt>master</tt> points the upstream and <tt>mybranch</tt> points your 838 working branch, and <tt>mybranch</tt> is rebased onto <tt>master</tt>. 839 At first you may check sanity of whitespaces: 840 </p> 841 842 <pre class="doc_code"> 843 git diff --check master..mybranch 844 </pre> 845 846 <p> 847 The easiest way to generate a patch is as below: 848 </p> 849 850 <pre class="doc_code"> 851 git diff master..mybranch > /path/to/mybranch.diff 852 </pre> 853 854 <p> 855 It is a little different from svn-generated diff. git-diff-generated diff has 856 prefixes like <tt>a/</tt> and <tt>b/</tt>. Don't worry, most developers might 857 know it could be accepted with <tt>patch -p1 -N</tt>. 858 </p> 859 860 <p> 861 But you may generate patchset with git-format-patch. It generates 862 by-each-commit patchset. To generate patch files to attach to your article: 863 </p> 864 865 <pre class="doc_code"> 866 git format-patch --no-attach master..mybranch -o /path/to/your/patchset 867 </pre> 868 869 <p> 870 If you would like to send patches directly, you may use git-send-email or 871 git-imap-send. Here is an example to generate the patchset in Gmail's [Drafts]. 872 </p> 873 874 <pre class="doc_code"> 875 git format-patch --attach master..mybranch --stdout | git imap-send 876 </pre> 877 878 <p> 879 Then, your .git/config should have [imap] sections. 880 </p> 881 882 <pre class="doc_code"> 883 [imap] 884 host = imaps://imap.gmail.com 885 user = <em>your.gmail.account</em>@gmail.com 886 pass = <em>himitsu!</em> 887 port = 993 888 sslverify = false 889 ; in English 890 folder = "[Gmail]/Drafts" 891 ; example for Japanese, "Modified UTF-7" encoded. 892 folder = "[Gmail]/&Tgtm+DBN-" 893 </pre> 894 895 </div> 896 897 <h4>For developers to work with git-svn</h4> 898 <div> 899 900 <p>To set up clone from which you can submit code using 901 <tt>git-svn</tt>, run:</p> 902 903 <pre class="doc_code"> 904 git clone http://llvm.org/git/llvm.git 905 cd llvm 906 git svn init https://llvm.org/svn/llvm-project/llvm/trunk --username=<username> 907 git config svn-remote.svn.fetch :refs/remotes/origin/master 908 git svn rebase -l # -l avoids fetching ahead of the git mirror. 909 910 # If you have clang too: 911 cd tools 912 git clone http://llvm.org/git/clang.git 913 cd clang 914 git svn init https://llvm.org/svn/llvm-project/cfe/trunk --username=<username> 915 git config svn-remote.svn.fetch :refs/remotes/origin/master 916 git svn rebase -l 917 </pre> 918 919 <p>To update this clone without generating git-svn tags that conflict 920 with the upstream git repo, run:</p> 921 922 <pre class="doc_code"> 923 git fetch && (cd tools/clang && git fetch) # Get matching revisions of both trees. 924 git checkout master 925 git svn rebase -l 926 (cd tools/clang && 927 git checkout master && 928 git svn rebase -l) 929 </pre> 930 931 <p>This leaves your working directories on their master branches, so 932 you'll need to <tt>checkout</tt> each working branch individually and 933 <tt>rebase</tt> it on top of its parent branch. (Note: This script is 934 intended for relative newbies to git. If you have more experience, 935 you can likely improve on it.)</p> 936 937 <p>The git-svn metadata can get out of sync after you mess around with 938 branches and <code>dcommit</code>. When that happens, <code>git svn 939 dcommit</code> stops working, complaining about files with uncommitted 940 changes. The fix is to rebuild the metadata:</p> 941 942 <pre class="doc_code"> 943 rm -rf .git/svn 944 git svn rebase -l 945 </pre> 946 947 </div> 948 949 </div> 950 951 <!-- ======================================================================= --> 952 <h3> 953 <a name="installcf">Install the GCC Front End</a> 954 </h3> 955 956 <div> 957 958 <p>Before configuring and compiling the LLVM suite (or if you want to use just the LLVM 959 GCC front end) you can optionally extract the front end from the binary distribution. 960 It is used for running the LLVM test-suite and for compiling C/C++ programs. Note that 961 you can optionally <a href="GCCFEBuildInstrs.html">build llvm-gcc yourself</a> after building the 962 main LLVM repository.</p> 963 964 <p>To install the GCC front end, do the following (on Windows, use an archival tool 965 like <a href="http://www.7-zip.org/">7-zip</a> that understands gzipped tars):</p> 966 967 <ol> 968 <li><tt>cd <i>where-you-want-the-front-end-to-live</i></tt></li> 969 <li><tt>gunzip --stdout llvm-gcc-4.2-<i>version</i>-<i>platform</i>.tar.gz | tar -xvf 970 -</tt></li> 971 </ol> 972 973 <p>Once the binary is uncompressed, if you're using a *nix-based system, add a symlink for 974 <tt>llvm-gcc</tt> and <tt>llvm-g++</tt> to some directory in your path. If you're using a 975 Windows-based system, add the <tt>bin</tt> subdirectory of your front end installation directory 976 to your <tt>PATH</tt> environment variable. For example, if you uncompressed the binary to 977 <tt>c:\llvm-gcc</tt>, add <tt>c:\llvm-gcc\bin</tt> to your <tt>PATH</tt>.</p> 978 979 <p>If you now want to build LLVM from source, when you configure LLVM, it will 980 automatically detect <tt>llvm-gcc</tt>'s presence (if it is in your path) enabling its 981 use in test-suite. Note that you can always build or install <tt>llvm-gcc</tt> at any 982 point after building the main LLVM repository: just reconfigure llvm and 983 test-suite will pick it up. 984 </p> 985 986 <p>As a convenience for Windows users, the front end binaries for MinGW/x86 include 987 versions of the required w32api and mingw-runtime binaries. The last remaining step for 988 Windows users is to simply uncompress the binary binutils package from 989 <a href="http://mingw.org/">MinGW</a> into your front end installation directory. While the 990 front end installation steps are not quite the same as a typical manual MinGW installation, 991 they should be similar enough to those who have previously installed MinGW on Windows systems.</p> 992 993 <p>To install binutils on Windows:</p> 994 995 <ol> 996 <li><tt><i>download GNU Binutils from <a href="http://sourceforge.net/projects/mingw/files/">MinGW Downloads</a></i></tt></li> 997 <li><tt>cd <i>where-you-uncompressed-the-front-end</i></tt></li> 998 <li><tt><i>uncompress archived binutils directories (not the tar file) into the current directory</i></tt></li> 999 </ol> 1000 1001 <p>The binary versions of the LLVM GCC front end may not suit all of your needs. For 1002 example, the binary distribution may include an old version of a system header 1003 file, not "fix" a header file that needs to be fixed for GCC, or it may be linked with 1004 libraries not available on your system. In cases like these, you may want to try 1005 <a href="GCCFEBuildInstrs.html">building the GCC front end from source</a>. Thankfully, 1006 this is much easier now than it was in the past.</p> 1007 1008 <p>We also do not currently support updating of the GCC front end by manually overlaying 1009 newer versions of the w32api and mingw-runtime binary packages that may become available 1010 from MinGW. At this time, it's best to think of the MinGW LLVM GCC front end binary as 1011 a self-contained convenience package that requires Windows users to simply download and 1012 uncompress the GNU Binutils binary package from the MinGW project.</p> 1013 1014 <p>Regardless of your platform, if you discover that installing the LLVM GCC front end 1015 binaries is not as easy as previously described, or you would like to suggest improvements, 1016 please let us know how you would like to see things improved by dropping us a note on our 1017 <a href="http://llvm.org/docs/#maillist">mailing list</a>.</p> 1018 1019 </div> 1020 1021 <!-- ======================================================================= --> 1022 <h3> 1023 <a name="config">Local LLVM Configuration</a> 1024 </h3> 1025 1026 <div> 1027 1028 <p>Once checked out from the Subversion repository, the LLVM suite source 1029 code must be 1030 configured via the <tt>configure</tt> script. This script sets variables in the 1031 various <tt>*.in</tt> files, most notably <tt>llvm/Makefile.config</tt> and 1032 <tt>llvm/include/Config/config.h</tt>. It also populates <i>OBJ_ROOT</i> with 1033 the Makefiles needed to begin building LLVM.</p> 1034 1035 <p>The following environment variables are used by the <tt>configure</tt> 1036 script to configure the build system:</p> 1037 1038 <table summary="LLVM configure script environment variables"> 1039 <tr><th>Variable</th><th>Purpose</th></tr> 1040 <tr> 1041 <td>CC</td> 1042 <td>Tells <tt>configure</tt> which C compiler to use. By default, 1043 <tt>configure</tt> will look for the first GCC C compiler in 1044 <tt>PATH</tt>. Use this variable to override 1045 <tt>configure</tt>'s default behavior.</td> 1046 </tr> 1047 <tr> 1048 <td>CXX</td> 1049 <td>Tells <tt>configure</tt> which C++ compiler to use. By default, 1050 <tt>configure</tt> will look for the first GCC C++ compiler in 1051 <tt>PATH</tt>. Use this variable to override 1052 <tt>configure</tt>'s default behavior.</td> 1053 </tr> 1054 </table> 1055 1056 <p>The following options can be used to set or enable LLVM specific options:</p> 1057 1058 <dl> 1059 <dt><i>--with-llvmgccdir</i></dt> 1060 <dd>Path to the LLVM C/C++ FrontEnd to be used with this LLVM configuration. 1061 The value of this option should specify the full pathname of the C/C++ Front 1062 End to be used. If this option is not provided, the PATH will be searched for 1063 a program named <i>llvm-gcc</i> and the C/C++ FrontEnd install directory will 1064 be inferred from the path found. If the option is not given, and no llvm-gcc 1065 can be found in the path then a warning will be produced by 1066 <tt>configure</tt> indicating this situation. LLVM may still be built with 1067 the <tt>tools-only</tt> target but attempting to build the runtime libraries 1068 will fail as these libraries require llvm-gcc and llvm-g++. See 1069 <a href="#installcf">Install the GCC Front End</a> for details on installing 1070 the C/C++ Front End. See 1071 <a href="GCCFEBuildInstrs.html">Bootstrapping the LLVM C/C++ Front-End</a> 1072 for details on building the C/C++ Front End.</dd> 1073 <dt><i>--with-tclinclude</i></dt> 1074 <dd>Path to the tcl include directory under which <tt>tclsh</tt> can be 1075 found. Use this if you have multiple tcl installations on your machine and you 1076 want to use a specific one (8.x) for LLVM. LLVM only uses tcl for running the 1077 dejagnu based test suite in <tt>llvm/test</tt>. If you don't specify this 1078 option, the LLVM configure script will search for the tcl 8.4 and 8.3 1079 releases. 1080 <br><br> 1081 </dd> 1082 <dt><i>--enable-optimized</i></dt> 1083 <dd> 1084 Enables optimized compilation (debugging symbols are removed 1085 and GCC optimization flags are enabled). Note that this is the default 1086 setting if you are using the LLVM distribution. The default behavior 1087 of an Subversion checkout is to use an unoptimized build (also known as a 1088 debug build). 1089 <br><br> 1090 </dd> 1091 <dt><i>--enable-debug-runtime</i></dt> 1092 <dd> 1093 Enables debug symbols in the runtime libraries. The default is to strip 1094 debug symbols from the runtime libraries. 1095 </dd> 1096 <dt><i>--enable-jit</i></dt> 1097 <dd> 1098 Compile the Just In Time (JIT) compiler functionality. This is not 1099 available 1100 on all platforms. The default is dependent on platform, so it is best 1101 to explicitly enable it if you want it. 1102 <br><br> 1103 </dd> 1104 <dt><i>--enable-targets=</i><tt>target-option</tt></dt> 1105 <dd>Controls which targets will be built and linked into llc. The default 1106 value for <tt>target_options</tt> is "all" which builds and links all 1107 available targets. The value "host-only" can be specified to build only a 1108 native compiler (no cross-compiler targets available). The "native" target is 1109 selected as the target of the build host. You can also specify a comma 1110 separated list of target names that you want available in llc. The target 1111 names use all lower case. The current set of targets is: <br> 1112 <tt>alpha, ia64, powerpc, skeleton, sparc, x86</tt>. 1113 <br><br></dd> 1114 <dt><i>--enable-doxygen</i></dt> 1115 <dd>Look for the doxygen program and enable construction of doxygen based 1116 documentation from the source code. This is disabled by default because 1117 generating the documentation can take a long time and producess 100s of 1118 megabytes of output.</dd> 1119 <dt><i>--with-udis86</i></dt> 1120 <dd>LLVM can use external disassembler library for various purposes (now it's 1121 used only for examining code produced by JIT). This option will enable usage 1122 of <a href="http://udis86.sourceforge.net/">udis86</a> x86 (both 32 and 64 1123 bits) disassembler library.</dd> 1124 </dl> 1125 1126 <p>To configure LLVM, follow these steps:</p> 1127 1128 <ol> 1129 <li><p>Change directory into the object root directory:</p> 1130 1131 <div class="doc_code"><pre>% cd <i>OBJ_ROOT</i></pre></div></li> 1132 1133 <li><p>Run the <tt>configure</tt> script located in the LLVM source 1134 tree:</p> 1135 1136 <div class="doc_code"> 1137 <pre>% <i>SRC_ROOT</i>/configure --prefix=/install/path [other options]</pre> 1138 </div></li> 1139 </ol> 1140 1141 </div> 1142 1143 <!-- ======================================================================= --> 1144 <h3> 1145 <a name="compile">Compiling the LLVM Suite Source Code</a> 1146 </h3> 1147 1148 <div> 1149 1150 <p>Once you have configured LLVM, you can build it. There are three types of 1151 builds:</p> 1152 1153 <dl> 1154 <dt>Debug Builds 1155 <dd> 1156 These builds are the default when one is using an Subversion checkout and 1157 types <tt>gmake</tt> (unless the <tt>--enable-optimized</tt> option was 1158 used during configuration). The build system will compile the tools and 1159 libraries with debugging information. To get a Debug Build using the 1160 LLVM distribution the <tt>--disable-optimized</tt> option must be passed 1161 to <tt>configure</tt>. 1162 <br><br> 1163 1164 <dt>Release (Optimized) Builds 1165 <dd> 1166 These builds are enabled with the <tt>--enable-optimized</tt> option to 1167 <tt>configure</tt> or by specifying <tt>ENABLE_OPTIMIZED=1</tt> on the 1168 <tt>gmake</tt> command line. For these builds, the build system will 1169 compile the tools and libraries with GCC optimizations enabled and strip 1170 debugging information from the libraries and executables it generates. 1171 Note that Release Builds are default when using an LLVM distribution. 1172 <br><br> 1173 1174 <dt>Profile Builds 1175 <dd> 1176 These builds are for use with profiling. They compile profiling 1177 information into the code for use with programs like <tt>gprof</tt>. 1178 Profile builds must be started by specifying <tt>ENABLE_PROFILING=1</tt> 1179 on the <tt>gmake</tt> command line. 1180 </dl> 1181 1182 <p>Once you have LLVM configured, you can build it by entering the 1183 <i>OBJ_ROOT</i> directory and issuing the following command:</p> 1184 1185 <div class="doc_code"><pre>% gmake</pre></div> 1186 1187 <p>If the build fails, please <a href="#brokengcc">check here</a> to see if you 1188 are using a version of GCC that is known not to compile LLVM.</p> 1189 1190 <p> 1191 If you have multiple processors in your machine, you may wish to use some of 1192 the parallel build options provided by GNU Make. For example, you could use the 1193 command:</p> 1194 1195 <div class="doc_code"><pre>% gmake -j2</pre></div> 1196 1197 <p>There are several special targets which are useful when working with the LLVM 1198 source code:</p> 1199 1200 <dl> 1201 <dt><tt>gmake clean</tt> 1202 <dd> 1203 Removes all files generated by the build. This includes object files, 1204 generated C/C++ files, libraries, and executables. 1205 <br><br> 1206 1207 <dt><tt>gmake dist-clean</tt> 1208 <dd> 1209 Removes everything that <tt>gmake clean</tt> does, but also removes files 1210 generated by <tt>configure</tt>. It attempts to return the source tree to the 1211 original state in which it was shipped. 1212 <br><br> 1213 1214 <dt><tt>gmake install</tt> 1215 <dd> 1216 Installs LLVM header files, libraries, tools, and documentation in a 1217 hierarchy 1218 under $PREFIX, specified with <tt>./configure --prefix=[dir]</tt>, which 1219 defaults to <tt>/usr/local</tt>. 1220 <br><br> 1221 1222 <dt><tt>gmake -C runtime install-bytecode</tt> 1223 <dd> 1224 Assuming you built LLVM into $OBJDIR, when this command is run, it will 1225 install bitcode libraries into the GCC front end's bitcode library 1226 directory. If you need to update your bitcode libraries, 1227 this is the target to use once you've built them. 1228 <br><br> 1229 </dl> 1230 1231 <p>Please see the <a href="MakefileGuide.html">Makefile Guide</a> for further 1232 details on these <tt>make</tt> targets and descriptions of other targets 1233 available.</p> 1234 1235 <p>It is also possible to override default values from <tt>configure</tt> by 1236 declaring variables on the command line. The following are some examples:</p> 1237 1238 <dl> 1239 <dt><tt>gmake ENABLE_OPTIMIZED=1</tt> 1240 <dd> 1241 Perform a Release (Optimized) build. 1242 <br><br> 1243 1244 <dt><tt>gmake ENABLE_OPTIMIZED=1 DISABLE_ASSERTIONS=1</tt> 1245 <dd> 1246 Perform a Release (Optimized) build without assertions enabled. 1247 <br><br> 1248 1249 <dt><tt>gmake ENABLE_OPTIMIZED=0</tt> 1250 <dd> 1251 Perform a Debug build. 1252 <br><br> 1253 1254 <dt><tt>gmake ENABLE_PROFILING=1</tt> 1255 <dd> 1256 Perform a Profiling build. 1257 <br><br> 1258 1259 <dt><tt>gmake VERBOSE=1</tt> 1260 <dd> 1261 Print what <tt>gmake</tt> is doing on standard output. 1262 <br><br> 1263 1264 <dt><tt>gmake TOOL_VERBOSE=1</tt></dt> 1265 <dd>Ask each tool invoked by the makefiles to print out what it is doing on 1266 the standard output. This also implies <tt>VERBOSE=1</tt>. 1267 <br><br></dd> 1268 </dl> 1269 1270 <p>Every directory in the LLVM object tree includes a <tt>Makefile</tt> to build 1271 it and any subdirectories that it contains. Entering any directory inside the 1272 LLVM object tree and typing <tt>gmake</tt> should rebuild anything in or below 1273 that directory that is out of date.</p> 1274 1275 </div> 1276 1277 <!-- ======================================================================= --> 1278 <h3> 1279 <a name="cross-compile">Cross-Compiling LLVM</a> 1280 </h3> 1281 1282 <div> 1283 <p>It is possible to cross-compile LLVM itself. That is, you can create LLVM 1284 executables and libraries to be hosted on a platform different from the 1285 platform where they are build (a Canadian Cross build). To configure a 1286 cross-compile, supply the configure script with <tt>--build</tt> and 1287 <tt>--host</tt> options that are different. The values of these options must 1288 be legal target triples that your GCC compiler supports.</p> 1289 1290 <p>The result of such a build is executables that are not runnable on 1291 on the build host (--build option) but can be executed on the compile host 1292 (--host option).</p> 1293 </div> 1294 1295 <!-- ======================================================================= --> 1296 <h3> 1297 <a name="objfiles">The Location of LLVM Object Files</a> 1298 </h3> 1299 1300 <div> 1301 1302 <p>The LLVM build system is capable of sharing a single LLVM source tree among 1303 several LLVM builds. Hence, it is possible to build LLVM for several different 1304 platforms or configurations using the same source tree.</p> 1305 1306 <p>This is accomplished in the typical autoconf manner:</p> 1307 1308 <ul> 1309 <li><p>Change directory to where the LLVM object files should live:</p> 1310 1311 <div class="doc_code"><pre>% cd <i>OBJ_ROOT</i></pre></div></li> 1312 1313 <li><p>Run the <tt>configure</tt> script found in the LLVM source 1314 directory:</p> 1315 1316 <div class="doc_code"><pre>% <i>SRC_ROOT</i>/configure</pre></div></li> 1317 </ul> 1318 1319 <p>The LLVM build will place files underneath <i>OBJ_ROOT</i> in directories 1320 named after the build type:</p> 1321 1322 <dl> 1323 <dt>Debug Builds with assertions enabled (the default) 1324 <dd> 1325 <dl> 1326 <dt>Tools 1327 <dd><tt><i>OBJ_ROOT</i>/Debug+Asserts/bin</tt> 1328 <dt>Libraries 1329 <dd><tt><i>OBJ_ROOT</i>/Debug+Asserts/lib</tt> 1330 </dl> 1331 <br><br> 1332 1333 <dt>Release Builds 1334 <dd> 1335 <dl> 1336 <dt>Tools 1337 <dd><tt><i>OBJ_ROOT</i>/Release/bin</tt> 1338 <dt>Libraries 1339 <dd><tt><i>OBJ_ROOT</i>/Release/lib</tt> 1340 </dl> 1341 <br><br> 1342 1343 <dt>Profile Builds 1344 <dd> 1345 <dl> 1346 <dt>Tools 1347 <dd><tt><i>OBJ_ROOT</i>/Profile/bin</tt> 1348 <dt>Libraries 1349 <dd><tt><i>OBJ_ROOT</i>/Profile/lib</tt> 1350 </dl> 1351 </dl> 1352 1353 </div> 1354 1355 <!-- ======================================================================= --> 1356 <h3> 1357 <a name="optionalconfig">Optional Configuration Items</a> 1358 </h3> 1359 1360 <div> 1361 1362 <p> 1363 If you're running on a Linux system that supports the "<a 1364 href="http://www.tat.physik.uni-tuebingen.de/~rguenth/linux/binfmt_misc.html">binfmt_misc</a>" 1365 module, and you have root access on the system, you can set your system up to 1366 execute LLVM bitcode files directly. To do this, use commands like this (the 1367 first command may not be required if you are already using the module):</p> 1368 1369 <div class="doc_code"> 1370 <pre> 1371 $ mount -t binfmt_misc none /proc/sys/fs/binfmt_misc 1372 $ echo ':llvm:M::BC::/path/to/lli:' > /proc/sys/fs/binfmt_misc/register 1373 $ chmod u+x hello.bc (if needed) 1374 $ ./hello.bc 1375 </pre> 1376 </div> 1377 1378 <p> 1379 This allows you to execute LLVM bitcode files directly. On Debian, you 1380 can also use this command instead of the 'echo' command above: 1381 </p> 1382 1383 <div class="doc_code"> 1384 <pre> 1385 $ sudo update-binfmts --install llvm /path/to/lli --magic 'BC' 1386 </pre> 1387 </div> 1388 1389 </div> 1390 1391 </div> 1392 1393 <!-- *********************************************************************** --> 1394 <h2> 1395 <a name="layout">Program Layout</a> 1396 </h2> 1397 <!-- *********************************************************************** --> 1398 1399 <div> 1400 1401 <p>One useful source of information about the LLVM source base is the LLVM <a 1402 href="http://www.doxygen.org/">doxygen</a> documentation available at <tt><a 1403 href="http://llvm.org/doxygen/">http://llvm.org/doxygen/</a></tt>. 1404 The following is a brief introduction to code layout:</p> 1405 1406 <!-- ======================================================================= --> 1407 <h3> 1408 <a name="examples"><tt>llvm/examples</tt></a> 1409 </h3> 1410 1411 <div> 1412 <p>This directory contains some simple examples of how to use the LLVM IR and 1413 JIT.</p> 1414 </div> 1415 1416 <!-- ======================================================================= --> 1417 <h3> 1418 <a name="include"><tt>llvm/include</tt></a> 1419 </h3> 1420 1421 <div> 1422 1423 <p>This directory contains public header files exported from the LLVM 1424 library. The three main subdirectories of this directory are:</p> 1425 1426 <dl> 1427 <dt><tt><b>llvm/include/llvm</b></tt></dt> 1428 <dd>This directory contains all of the LLVM specific header files. This 1429 directory also has subdirectories for different portions of LLVM: 1430 <tt>Analysis</tt>, <tt>CodeGen</tt>, <tt>Target</tt>, <tt>Transforms</tt>, 1431 etc...</dd> 1432 1433 <dt><tt><b>llvm/include/llvm/Support</b></tt></dt> 1434 <dd>This directory contains generic support libraries that are provided with 1435 LLVM but not necessarily specific to LLVM. For example, some C++ STL utilities 1436 and a Command Line option processing library store their header files here. 1437 </dd> 1438 1439 <dt><tt><b>llvm/include/llvm/Config</b></tt></dt> 1440 <dd>This directory contains header files configured by the <tt>configure</tt> 1441 script. They wrap "standard" UNIX and C header files. Source code can 1442 include these header files which automatically take care of the conditional 1443 #includes that the <tt>configure</tt> script generates.</dd> 1444 </dl> 1445 </div> 1446 1447 <!-- ======================================================================= --> 1448 <h3> 1449 <a name="lib"><tt>llvm/lib</tt></a> 1450 </h3> 1451 1452 <div> 1453 1454 <p>This directory contains most of the source files of the LLVM system. In LLVM, 1455 almost all code exists in libraries, making it very easy to share code among the 1456 different <a href="#tools">tools</a>.</p> 1457 1458 <dl> 1459 <dt><tt><b>llvm/lib/VMCore/</b></tt></dt> 1460 <dd> This directory holds the core LLVM source files that implement core 1461 classes like Instruction and BasicBlock.</dd> 1462 1463 <dt><tt><b>llvm/lib/AsmParser/</b></tt></dt> 1464 <dd>This directory holds the source code for the LLVM assembly language parser 1465 library.</dd> 1466 1467 <dt><tt><b>llvm/lib/BitCode/</b></tt></dt> 1468 <dd>This directory holds code for reading and write LLVM bitcode.</dd> 1469 1470 <dt><tt><b>llvm/lib/Analysis/</b></tt><dd>This directory contains a variety of 1471 different program analyses, such as Dominator Information, Call Graphs, 1472 Induction Variables, Interval Identification, Natural Loop Identification, 1473 etc.</dd> 1474 1475 <dt><tt><b>llvm/lib/Transforms/</b></tt></dt> 1476 <dd> This directory contains the source code for the LLVM to LLVM program 1477 transformations, such as Aggressive Dead Code Elimination, Sparse Conditional 1478 Constant Propagation, Inlining, Loop Invariant Code Motion, Dead Global 1479 Elimination, and many others.</dd> 1480 1481 <dt><tt><b>llvm/lib/Target/</b></tt></dt> 1482 <dd> This directory contains files that describe various target architectures 1483 for code generation. For example, the <tt>llvm/lib/Target/X86</tt> 1484 directory holds the X86 machine description while 1485 <tt>llvm/lib/Target/CBackend</tt> implements the LLVM-to-C converter.</dd> 1486 1487 <dt><tt><b>llvm/lib/CodeGen/</b></tt></dt> 1488 <dd> This directory contains the major parts of the code generator: Instruction 1489 Selector, Instruction Scheduling, and Register Allocation.</dd> 1490 1491 <dt><tt><b>llvm/lib/MC/</b></tt></dt> 1492 <dd>(FIXME: T.B.D.)</dd> 1493 1494 <!--FIXME: obsoleted --> 1495 <dt><tt><b>llvm/lib/Debugger/</b></tt></dt> 1496 <dd> This directory contains the source level debugger library that makes 1497 it possible to instrument LLVM programs so that a debugger could identify 1498 source code locations at which the program is executing.</dd> 1499 1500 <dt><tt><b>llvm/lib/ExecutionEngine/</b></tt></dt> 1501 <dd> This directory contains libraries for executing LLVM bitcode directly 1502 at runtime in both interpreted and JIT compiled fashions.</dd> 1503 1504 <dt><tt><b>llvm/lib/Support/</b></tt></dt> 1505 <dd> This directory contains the source code that corresponds to the header 1506 files located in <tt>llvm/include/ADT/</tt> 1507 and <tt>llvm/include/Support/</tt>.</dd> 1508 </dl> 1509 1510 </div> 1511 1512 <!-- ======================================================================= --> 1513 <h3> 1514 <a name="projects"><tt>llvm/projects</tt></a> 1515 </h3> 1516 1517 <div> 1518 <p>This directory contains projects that are not strictly part of LLVM but are 1519 shipped with LLVM. This is also the directory where you should create your own 1520 LLVM-based projects. See <tt>llvm/projects/sample</tt> for an example of how 1521 to set up your own project.</p> 1522 </div> 1523 1524 <!-- ======================================================================= --> 1525 <h3> 1526 <a name="runtime"><tt>llvm/runtime</tt></a> 1527 </h3> 1528 1529 <div> 1530 1531 <p>This directory contains libraries which are compiled into LLVM bitcode and 1532 used when linking programs with the GCC front end. Most of these libraries are 1533 skeleton versions of real libraries; for example, libc is a stripped down 1534 version of glibc.</p> 1535 1536 <p>Unlike the rest of the LLVM suite, this directory needs the LLVM GCC front 1537 end to compile.</p> 1538 1539 </div> 1540 1541 <!-- ======================================================================= --> 1542 <h3> 1543 <a name="test"><tt>llvm/test</tt></a> 1544 </h3> 1545 1546 <div> 1547 <p>This directory contains feature and regression tests and other basic sanity 1548 checks on the LLVM infrastructure. These are intended to run quickly and cover 1549 a lot of territory without being exhaustive.</p> 1550 </div> 1551 1552 <!-- ======================================================================= --> 1553 <h3> 1554 <a name="test-suite"><tt>test-suite</tt></a> 1555 </h3> 1556 1557 <div> 1558 <p>This is not a directory in the normal llvm module; it is a separate 1559 Subversion 1560 module that must be checked out (usually to <tt>projects/test-suite</tt>). 1561 This 1562 module contains a comprehensive correctness, performance, and benchmarking 1563 test 1564 suite for LLVM. It is a separate Subversion module because not every LLVM 1565 user is 1566 interested in downloading or building such a comprehensive test suite. For 1567 further details on this test suite, please see the 1568 <a href="TestingGuide.html">Testing Guide</a> document.</p> 1569 </div> 1570 1571 <!-- ======================================================================= --> 1572 <h3> 1573 <a name="tools"><tt>llvm/tools</tt></a> 1574 </h3> 1575 1576 <div> 1577 1578 <p>The <b>tools</b> directory contains the executables built out of the 1579 libraries above, which form the main part of the user interface. You can 1580 always get help for a tool by typing <tt>tool_name -help</tt>. The 1581 following is a brief introduction to the most important tools. More detailed 1582 information is in the <a href="CommandGuide/index.html">Command Guide</a>.</p> 1583 1584 <dl> 1585 1586 <dt><tt><b>bugpoint</b></tt></dt> 1587 <dd><tt>bugpoint</tt> is used to debug 1588 optimization passes or code generation backends by narrowing down the 1589 given test case to the minimum number of passes and/or instructions that 1590 still cause a problem, whether it is a crash or miscompilation. See <a 1591 href="HowToSubmitABug.html">HowToSubmitABug.html</a> for more information 1592 on using <tt>bugpoint</tt>.</dd> 1593 1594 <dt><tt><b>llvm-ar</b></tt></dt> 1595 <dd>The archiver produces an archive containing 1596 the given LLVM bitcode files, optionally with an index for faster 1597 lookup.</dd> 1598 1599 <dt><tt><b>llvm-as</b></tt></dt> 1600 <dd>The assembler transforms the human readable LLVM assembly to LLVM 1601 bitcode.</dd> 1602 1603 <dt><tt><b>llvm-dis</b></tt></dt> 1604 <dd>The disassembler transforms the LLVM bitcode to human readable 1605 LLVM assembly.</dd> 1606 1607 <dt><tt><b>llvm-ld</b></tt></dt> 1608 <dd><tt>llvm-ld</tt> is a general purpose and extensible linker for LLVM. 1609 It performs standard link time optimizations and allows optimization 1610 modules to be loaded and run so that language specific optimizations can 1611 be applied at link time.</dd> 1612 1613 <dt><tt><b>llvm-link</b></tt></dt> 1614 <dd><tt>llvm-link</tt>, not surprisingly, links multiple LLVM modules into 1615 a single program.</dd> 1616 1617 <dt><tt><b>lli</b></tt></dt> 1618 <dd><tt>lli</tt> is the LLVM interpreter, which 1619 can directly execute LLVM bitcode (although very slowly...). For architectures 1620 that support it (currently x86, Sparc, and PowerPC), by default, <tt>lli</tt> 1621 will function as a Just-In-Time compiler (if the functionality was compiled 1622 in), and will execute the code <i>much</i> faster than the interpreter.</dd> 1623 1624 <dt><tt><b>llc</b></tt></dt> 1625 <dd> <tt>llc</tt> is the LLVM backend compiler, which 1626 translates LLVM bitcode to a native code assembly file or to C code (with 1627 the -march=c option).</dd> 1628 1629 <dt><tt><b>llvm-gcc</b></tt></dt> 1630 <dd><tt>llvm-gcc</tt> is a GCC-based C frontend that has been retargeted to 1631 use LLVM as its backend instead of GCC's RTL backend. It can also emit LLVM 1632 bitcode or assembly (with the <tt>-emit-llvm</tt> option) instead of the 1633 usual machine code output. It works just like any other GCC compiler, 1634 taking the typical <tt>-c, -S, -E, -o</tt> options that are typically used. 1635 Additionally, the the source code for <tt>llvm-gcc</tt> is available as a 1636 separate Subversion module.</dd> 1637 1638 <dt><tt><b>opt</b></tt></dt> 1639 <dd><tt>opt</tt> reads LLVM bitcode, applies a series of LLVM to LLVM 1640 transformations (which are specified on the command line), and then outputs 1641 the resultant bitcode. The '<tt>opt -help</tt>' command is a good way to 1642 get a list of the program transformations available in LLVM.<br> 1643 <dd><tt>opt</tt> can also be used to run a specific analysis on an input 1644 LLVM bitcode file and print out the results. It is primarily useful for 1645 debugging analyses, or familiarizing yourself with what an analysis does.</dd> 1646 </dl> 1647 </div> 1648 1649 <!-- ======================================================================= --> 1650 <h3> 1651 <a name="utils"><tt>llvm/utils</tt></a> 1652 </h3> 1653 1654 <div> 1655 1656 <p>This directory contains utilities for working with LLVM source code, and some 1657 of the utilities are actually required as part of the build process because they 1658 are code generators for parts of LLVM infrastructure.</p> 1659 1660 <dl> 1661 <dt><tt><b>codegen-diff</b></tt> <dd><tt>codegen-diff</tt> is a script 1662 that finds differences between code that LLC generates and code that LLI 1663 generates. This is a useful tool if you are debugging one of them, 1664 assuming that the other generates correct output. For the full user 1665 manual, run <tt>`perldoc codegen-diff'</tt>.<br><br> 1666 1667 <dt><tt><b>emacs/</b></tt> <dd>The <tt>emacs</tt> directory contains 1668 syntax-highlighting files which will work with Emacs and XEmacs editors, 1669 providing syntax highlighting support for LLVM assembly files and TableGen 1670 description files. For information on how to use the syntax files, consult 1671 the <tt>README</tt> file in that directory.<br><br> 1672 1673 <dt><tt><b>getsrcs.sh</b></tt> <dd>The <tt>getsrcs.sh</tt> script finds 1674 and outputs all non-generated source files, which is useful if one wishes 1675 to do a lot of development across directories and does not want to 1676 individually find each file. One way to use it is to run, for example: 1677 <tt>xemacs `utils/getsources.sh`</tt> from the top of your LLVM source 1678 tree.<br><br> 1679 1680 <dt><tt><b>llvmgrep</b></tt></dt> 1681 <dd>This little tool performs an "egrep -H -n" on each source file in LLVM and 1682 passes to it a regular expression provided on <tt>llvmgrep</tt>'s command 1683 line. This is a very efficient way of searching the source base for a 1684 particular regular expression.</dd> 1685 1686 <dt><tt><b>makellvm</b></tt> <dd>The <tt>makellvm</tt> script compiles all 1687 files in the current directory and then compiles and links the tool that 1688 is the first argument. For example, assuming you are in the directory 1689 <tt>llvm/lib/Target/Sparc</tt>, if <tt>makellvm</tt> is in your path, 1690 simply running <tt>makellvm llc</tt> will make a build of the current 1691 directory, switch to directory <tt>llvm/tools/llc</tt> and build it, 1692 causing a re-linking of LLC.<br><br> 1693 1694 <dt><tt><b>NewNightlyTest.pl</b></tt> and 1695 <tt><b>NightlyTestTemplate.html</b></tt> <dd>These files are used in a 1696 cron script to generate nightly status reports of the functionality of 1697 tools, and the results can be seen by following the appropriate link on 1698 the <a href="http://llvm.org/">LLVM homepage</a>.<br><br> 1699 1700 <dt><tt><b>TableGen/</b></tt> <dd>The <tt>TableGen</tt> directory contains 1701 the tool used to generate register descriptions, instruction set 1702 descriptions, and even assemblers from common TableGen description 1703 files.<br><br> 1704 1705 <dt><tt><b>vim/</b></tt> <dd>The <tt>vim</tt> directory contains 1706 syntax-highlighting files which will work with the VIM editor, providing 1707 syntax highlighting support for LLVM assembly files and TableGen 1708 description files. For information on how to use the syntax files, consult 1709 the <tt>README</tt> file in that directory.<br><br> 1710 1711 </dl> 1712 1713 </div> 1714 1715 </div> 1716 1717 <!-- *********************************************************************** --> 1718 <h2> 1719 <a name="tutorial">An Example Using the LLVM Tool Chain</a> 1720 </h2> 1721 <!-- *********************************************************************** --> 1722 1723 <div> 1724 <p>This section gives an example of using LLVM. llvm-gcc3 is now obsolete, 1725 so we only include instructions for llvm-gcc4. 1726 </p> 1727 1728 <p><b>Note:</b> The <i>gcc4</i> frontend's invocation is <b><i>considerably different</i></b> 1729 from the previous <i>gcc3</i> frontend. In particular, the <i>gcc4</i> frontend <b><i>does not</i></b> 1730 create bitcode by default: <i>gcc4</i> produces native code. As the example below illustrates, 1731 the '--emit-llvm' flag is needed to produce LLVM bitcode output. For <i>makefiles</i> and 1732 <i>configure</i> scripts, the CFLAGS variable needs '--emit-llvm' to produce bitcode 1733 output.</p> 1734 1735 <!-- ======================================================================= --> 1736 <h3> 1737 <a name="tutorial4">Example with llvm-gcc4</a> 1738 </h3> 1739 1740 <div> 1741 1742 <ol> 1743 <li><p>First, create a simple C file, name it 'hello.c':</p> 1744 1745 <div class="doc_code"> 1746 <pre> 1747 #include <stdio.h> 1748 1749 int main() { 1750 printf("hello world\n"); 1751 return 0; 1752 } 1753 </pre></div></li> 1754 1755 <li><p>Next, compile the C file into a native executable:</p> 1756 1757 <div class="doc_code"><pre>% llvm-gcc hello.c -o hello</pre></div> 1758 1759 <p>Note that llvm-gcc works just like GCC by default. The standard -S and 1760 -c arguments work as usual (producing a native .s or .o file, 1761 respectively).</p></li> 1762 1763 <li><p>Next, compile the C file into a LLVM bitcode file:</p> 1764 1765 <div class="doc_code"> 1766 <pre>% llvm-gcc -O3 -emit-llvm hello.c -c -o hello.bc</pre></div> 1767 1768 <p>The -emit-llvm option can be used with the -S or -c options to emit an 1769 LLVM ".ll" or ".bc" file (respectively) for the code. This allows you 1770 to use the <a href="CommandGuide/index.html">standard LLVM tools</a> on 1771 the bitcode file.</p> 1772 1773 <p>Unlike llvm-gcc3, llvm-gcc4 correctly responds to -O[0123] arguments. 1774 </p></li> 1775 1776 <li><p>Run the program in both forms. To run the program, use:</p> 1777 1778 <div class="doc_code"><pre>% ./hello</pre></div> 1779 1780 <p>and</p> 1781 1782 <div class="doc_code"><pre>% lli hello.bc</pre></div> 1783 1784 <p>The second examples shows how to invoke the LLVM JIT, <a 1785 href="CommandGuide/html/lli.html">lli</a>.</p></li> 1786 1787 <li><p>Use the <tt>llvm-dis</tt> utility to take a look at the LLVM assembly 1788 code:</p> 1789 1790 <div class="doc_code"> 1791 <pre>llvm-dis < hello.bc | less</pre> 1792 </div></li> 1793 1794 <li><p>Compile the program to native assembly using the LLC code 1795 generator:</p> 1796 1797 <div class="doc_code"><pre>% llc hello.bc -o hello.s</pre></div></li> 1798 1799 <li><p>Assemble the native assembly language file into a program:</p> 1800 1801 <div class="doc_code"> 1802 <pre> 1803 <b>Solaris:</b> % /opt/SUNWspro/bin/cc -xarch=v9 hello.s -o hello.native 1804 1805 <b>Others:</b> % gcc hello.s -o hello.native 1806 </pre> 1807 </div></li> 1808 1809 <li><p>Execute the native code program:</p> 1810 1811 <div class="doc_code"><pre>% ./hello.native</pre></div> 1812 1813 <p>Note that using llvm-gcc to compile directly to native code (i.e. when 1814 the -emit-llvm option is not present) does steps 6/7/8 for you.</p> 1815 </li> 1816 1817 </ol> 1818 1819 </div> 1820 1821 </div> 1822 1823 <!-- *********************************************************************** --> 1824 <h2> 1825 <a name="problems">Common Problems</a> 1826 </h2> 1827 <!-- *********************************************************************** --> 1828 1829 <div> 1830 1831 <p>If you are having problems building or using LLVM, or if you have any other 1832 general questions about LLVM, please consult the <a href="FAQ.html">Frequently 1833 Asked Questions</a> page.</p> 1834 1835 </div> 1836 1837 <!-- *********************************************************************** --> 1838 <h2> 1839 <a name="links">Links</a> 1840 </h2> 1841 <!-- *********************************************************************** --> 1842 1843 <div> 1844 1845 <p>This document is just an <b>introduction</b> on how to use LLVM to do 1846 some simple things... there are many more interesting and complicated things 1847 that you can do that aren't documented here (but we'll gladly accept a patch 1848 if you want to write something up!). For more information about LLVM, check 1849 out:</p> 1850 1851 <ul> 1852 <li><a href="http://llvm.org/">LLVM homepage</a></li> 1853 <li><a href="http://llvm.org/doxygen/">LLVM doxygen tree</a></li> 1854 <li><a href="http://llvm.org/docs/Projects.html">Starting a Project 1855 that Uses LLVM</a></li> 1856 </ul> 1857 1858 </div> 1859 1860 <!-- *********************************************************************** --> 1861 1862 <hr> 1863 <address> 1864 <a href="http://jigsaw.w3.org/css-validator/check/referer"><img 1865 src="http://jigsaw.w3.org/css-validator/images/vcss-blue" alt="Valid CSS"></a> 1866 <a href="http://validator.w3.org/check/referer"><img 1867 src="http://www.w3.org/Icons/valid-html401-blue" alt="Valid HTML 4.01"></a> 1868 1869 <a href="mailto:sabre (a] nondot.org">Chris Lattner</a><br> 1870 <a href="http://llvm.x10sys.com/rspencer/">Reid Spencer</a><br> 1871 <a href="http://llvm.org/">The LLVM Compiler Infrastructure</a><br> 1872 Last modified: $Date$ 1873 </address> 1874 </body> 1875 </html> 1876
