docs/FAQ.html

   1 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN"
   2                       "http://www.w3.org/TR/html4/strict.dtd">
   3 <html>
   4 <head>
   5   <meta http-equiv="Content-Type" content="text/html; charset=utf-8">
   6   <title>LLVM: Frequently Asked Questions</title>
   7   <style type="text/css">
   8     @import url("llvm.css");
   9     .question { font-weight: bold }
  10     .answer   { margin-left: 2em  }
  11   </style>
  12 </head>
  13 <body>
  14
  15 <div class="doc_title">
  16   LLVM: Frequently Asked Questions
  17 </div>
  18
  19 <ol>
  20   <li><a href="#license">License</a>
  21   <ol>
  22     <li>Why are the LLVM source code and the front-end distributed under
  23         different licenses?</li>
  24
  25     <li>Does the University of Illinois Open Source License really qualify as an
  26        "open source" license?</li>
  27
  28     <li>Can I modify LLVM source code and redistribute the modified source?</li>
  29
  30     <li>Can I modify LLVM source code and redistribute binaries or other tools
  31         based on it, without redistributing the source?</li>
  32   </ol></li>
  33
  34   <li><a href="#source">Source code</a>
  35   <ol>
  36     <li>In what language is LLVM written?</li>
  37
  38     <li>How portable is the LLVM source code?</li>
  39   </ol></li>
  40
  41   <li><a href="#build">Build Problems</a>
  42   <ol>
  43     <li>When I run configure, it finds the wrong C compiler.</li>
  44
  45     <li>The <tt>configure</tt> script finds the right C compiler, but it uses
  46         the LLVM linker from a previous build.  What do I do?</li>
  47
  48     <li>When creating a dynamic library, I get a strange GLIBC error.</li>
  49
  50     <li>I've updated my source tree from Subversion, and now my build is trying
  51         to use a file/directory that doesn't exist.</li>
  52
  53     <li>I've modified a Makefile in my source tree, but my build tree keeps
  54         using the old version.  What do I do?</li>
  55
  56     <li>I've upgraded to a new version of LLVM, and I get strange build
  57         errors.</li>
  58
  59     <li>I've built LLVM and am testing it, but the tests freeze.</li>
  60
  61     <li>Why do test results differ when I perform different types of
  62         builds?</li>
  63
  64     <li>Compiling LLVM with GCC 3.3.2 fails, what should I do?</li>
  65
  66     <li>Compiling LLVM with GCC succeeds, but the resulting tools do not work,
  67         what can be wrong?</li>
  68
  69     <li>When I use the test suite, all of the C Backend tests fail.  What is
  70         wrong?</li>
  71
  72     <li>After Subversion update, rebuilding gives the error "No rule to make
  73         target".</li>
  74
  75     <li><a href="#llvmc">The <tt>llvmc</tt> program gives me errors/doesn't
  76         work.</a></li>
  77
  78     <li><a href="#srcdir-objdir">When I compile LLVM-GCC with srcdir == objdir,
  79         it fails. Why?</a></li>
  80   </ol></li>
  81
  82   <li><a href="#felangs">Source Languages</a>
  83   <ol>
  84     <li><a href="#langs">What source languages are supported?</a></li>
  85
  86     <li><a href="#langirgen">I'd like to write a self-hosting LLVM compiler. How
  87         should I interface with the LLVM middle-end optimizers and back-end code
  88         generators?</a></li>
  89
  90     <li><a href="#langhlsupp">What support is there for higher level source
  91         language constructs for building a compiler?</a></li>
  92
  93     <li><a href="GetElementPtr.html">I don't understand the GetElementPtr
  94       instruction. Help!</a></li>
  95   </ol>
  96
  97   <li><a href="#cfe">Using the GCC Front End</a>
  98   <ol>
  99     <li>When I compile software that uses a configure script, the configure
 100         script thinks my system has all of the header files and libraries it is
 101         testing for.  How do I get configure to work correctly?</li>
 102
 103     <li>When I compile code using the LLVM GCC front end, it complains that it
 104         cannot find libcrtend.a?</li>
 105
 106     <li>How can I disable all optimizations when compiling code using the LLVM
 107         GCC front end?</li>
 108
 109     <li><a href="#translatecxx">Can I use LLVM to convert C++ code to C
 110         code?</a></li>
 111
 112     <li><a href="#platformindependent">Can I compile C or C++ code to
 113         platform-independent LLVM bitcode?</a></li>
 114   </ol>
 115   </li>
 116
 117   <li><a href="#cfe_code">Questions about code generated by the GCC front-end</a>
 118   <ol>
 119      <li><a href="#iosinit">What is this <tt>llvm.global_ctors</tt> and
 120           <tt>_GLOBAL__I__tmp_webcompile...</tt> stuff that happens when I
 121           #include &lt;iostream&gt;?</a></li>
 122
 123      <li><a href="#codedce">Where did all of my code go??</a></li>
 124
 125      <li><a href="#undef">What is this "<tt>undef</tt>" thing that shows up in
 126          my code?</a></li>
 127   </ol>
 128   </li>
 129 </ol>
 130
 131 <div class="doc_author">
 132   <p>Written by <a href="http://llvm.org">The LLVM Team</a></p>
 133 </div>
 134
 135
 136 <!-- *********************************************************************** -->
 137 <div class="doc_section">
 138   <a name="license">License</a>
 139 </div>
 140 <!-- *********************************************************************** -->
 141
 142 <div class="question">
 143 <p>Why are the LLVM source code and the front-end distributed under different
 144    licenses?</p>
 145 </div>
 146
 147 <div class="answer">
 148 <p>The C/C++ front-ends are based on GCC and must be distributed under the GPL.
 149    Our aim is to distribute LLVM source code under a <em>much less
 150    restrictive</em> license, in particular one that does not compel users who
 151    distribute tools based on modifying the source to redistribute the modified
 152    source code as well.</p>
 153 </div>
 154
 155 <div class="question">
 156 <p>Does the University of Illinois Open Source License really qualify as an
 157    "open source" license?</p>
 158 </div>
 159
 160 <div class="answer">
 161 <p>Yes, the license
 162    is <a href="http://www.opensource.org/licenses/UoI-NCSA.php">certified</a> by
 163    the Open Source Initiative (OSI).</p>
 164 </div>
 165
 166 <div class="question">
 167 <p>Can I modify LLVM source code and redistribute the modified source?</p>
 168 </div>
 169
 170 <div class="answer">
 171 <p>Yes.  The modified source distribution must retain the copyright notice and
 172    follow the three bulletted conditions listed in
 173    the <a href="http://llvm.org/svn/llvm-project/llvm/trunk/LICENSE.TXT">LLVM
 174    license</a>.</p>
 175 </div>
 176
 177 <div class="question">
 178 <p>Can I modify LLVM source code and redistribute binaries or other tools based
 179    on it, without redistributing the source?</p>
 180 </div>
 181
 182 <div class="answer">
 183 <p>Yes. This is why we distribute LLVM under a less restrictive license than
 184    GPL, as explained in the first question above.</p>
 185 </div>
 186
 187 <!-- *********************************************************************** -->
 188 <div class="doc_section">
 189   <a name="source">Source Code</a>
 190 </div>
 191 <!-- *********************************************************************** -->
 192
 193 <div class="question">
 194 <p>In what language is LLVM written?</p>
 195 </div>
 196
 197 <div class="answer">
 198 <p>All of the LLVM tools and libraries are written in C++ with extensive use of
 199    the STL.</p>
 200 </div>
 201
 202 <div class="question">
 203 <p>How portable is the LLVM source code?</p>
 204 </div>
 205
 206 <div class="answer">
 207 <p>The LLVM source code should be portable to most modern UNIX-like operating
 208 systems.  Most of the code is written in standard C++ with operating system
 209 services abstracted to a support library.  The tools required to build and test
 210 LLVM have been ported to a plethora of platforms.</p>
 211
 212 <p>Some porting problems may exist in the following areas:</p>
 213
 214 <ul>
 215   <li>The GCC front end code is not as portable as the LLVM suite, so it may not
 216       compile as well on unsupported platforms.</li>
 217
 218   <li>The LLVM build system relies heavily on UNIX shell tools, like the Bourne
 219       Shell and sed.  Porting to systems without these tools (MacOS 9, Plan 9)
 220       will require more effort.</li>
 221 </ul>
 222
 223 </div>
 224
 225 <!-- *********************************************************************** -->
 226 <div class="doc_section">
 227   <a name="build">Build Problems</a>
 228 </div>
 229 <!-- *********************************************************************** -->
 230
 231 <div class="question">
 232 <p>When I run configure, it finds the wrong C compiler.</p>
 233 </div>
 234
 235 <div class="answer">
 236 <p>The <tt>configure</tt> script attempts to locate first <tt>gcc</tt> and then
 237    <tt>cc</tt>, unless it finds compiler paths set in <tt>CC</tt>
 238    and <tt>CXX</tt> for the C and C++ compiler, respectively.</p>
 239
 240 <p>If <tt>configure</tt> finds the wrong compiler, either adjust your
 241    <tt>PATH</tt> environment variable or set <tt>CC</tt> and <tt>CXX</tt>
 242    explicitly.</p>
 243
 244 </div>
 245
 246 <div class="question">
 247 <p>The <tt>configure</tt> script finds the right C compiler, but it uses the
 248    LLVM linker from a previous build.  What do I do?</p>
 249 </div>
 250
 251 <div class="answer">
 252 <p>The <tt>configure</tt> script uses the <tt>PATH</tt> to find executables, so
 253    if it's grabbing the wrong linker/assembler/etc, there are two ways to fix
 254    it:</p>
 255
 256 <ol>
 257   <li><p>Adjust your <tt>PATH</tt> environment variable so that the correct
 258       program appears first in the <tt>PATH</tt>.  This may work, but may not be
 259       convenient when you want them <i>first</i> in your path for other
 260       work.</p></li>
 261
 262   <li><p>Run <tt>configure</tt> with an alternative <tt>PATH</tt> that is
 263       correct. In a Borne compatible shell, the syntax would be:</p>
 264
 265 <pre class="doc_code">
 266 % PATH=[the path without the bad program] ./configure ...
 267 </pre>
 268
 269       <p>This is still somewhat inconvenient, but it allows <tt>configure</tt>
 270          to do its work without having to adjust your <tt>PATH</tt>
 271          permanently.</p></li>
 272 </ol>
 273 </div>
 274
 275 <div class="question">
 276 <p>When creating a dynamic library, I get a strange GLIBC error.</p>
 277 </div>
 278
 279 <div class="answer">
 280 <p>Under some operating systems (i.e. Linux), libtool does not work correctly if
 281    GCC was compiled with the --disable-shared option.  To work around this,
 282    install your own version of GCC that has shared libraries enabled by
 283    default.</p>
 284 </div>
 285
 286 <div class="question">
 287 <p>I've updated my source tree from Subversion, and now my build is trying to
 288    use a file/directory that doesn't exist.</p>
 289 </div>
 290
 291 <div class="answer">
 292 <p>You need to re-run configure in your object directory.  When new Makefiles
 293    are added to the source tree, they have to be copied over to the object tree
 294    in order to be used by the build.</p>
 295 </div>
 296
 297 <div class="question">
 298 <p>I've modified a Makefile in my source tree, but my build tree keeps using the
 299    old version.  What do I do?</p>
 300 </div>
 301
 302 <div class="answer">
 303 <p>If the Makefile already exists in your object tree, you can just run the
 304    following command in the top level directory of your object tree:</p>
 305
 306 <pre class="doc_code">
 307 % ./config.status &lt;relative path to Makefile&gt;
 308 </pre>
 309
 310 <p>If the Makefile is new, you will have to modify the configure script to copy
 311    it over.</p>
 312 </div>
 313
 314 <div class="question">
 315 <p>I've upgraded to a new version of LLVM, and I get strange build errors.</p>
 316 </div>
 317
 318 <div class="answer">
 319
 320 <p>Sometimes, changes to the LLVM source code alters how the build system works.
 321    Changes in libtool, autoconf, or header file dependencies are especially
 322    prone to this sort of problem.</p>
 323
 324 <p>The best thing to try is to remove the old files and re-build.  In most
 325    cases, this takes care of the problem.  To do this, just type <tt>make
 326    clean</tt> and then <tt>make</tt> in the directory that fails to build.</p>
 327 </div>
 328
 329 <div class="question">
 330 <p>I've built LLVM and am testing it, but the tests freeze.</p>
 331 </div>
 332
 333 <div class="answer">
 334 <p>This is most likely occurring because you built a profile or release
 335    (optimized) build of LLVM and have not specified the same information on the
 336    <tt>gmake</tt> command line.</p>
 337
 338 <p>For example, if you built LLVM with the command:</p>
 339
 340 <pre class="doc_code">
 341 % gmake ENABLE_PROFILING=1
 342 </pre>
 343
 344 <p>...then you must run the tests with the following commands:</p>
 345
 346 <pre class="doc_code">
 347 % cd llvm/test
 348 % gmake ENABLE_PROFILING=1
 349 </pre>
 350 </div>
 351
 352 <div class="question">
 353 <p>Why do test results differ when I perform different types of builds?</p>
 354 </div>
 355
 356 <div class="answer">
 357 <p>The LLVM test suite is dependent upon several features of the LLVM tools and
 358    libraries.</p>
 359
 360 <p>First, the debugging assertions in code are not enabled in optimized or
 361    profiling builds.  Hence, tests that used to fail may pass.</p>
 362
 363 <p>Second, some tests may rely upon debugging options or behavior that is only
 364    available in the debug build.  These tests will fail in an optimized or
 365    profile build.</p>
 366 </div>
 367
 368 <div class="question">
 369 <p>Compiling LLVM with GCC 3.3.2 fails, what should I do?</p>
 370 </div>
 371
 372 <div class="answer">
 373 <p>This is <a href="http://gcc.gnu.org/bugzilla/show_bug.cgi?id=13392">a bug in
 374    GCC</a>, and affects projects other than LLVM.  Try upgrading or downgrading
 375    your GCC.</p>
 376 </div>
 377
 378 <div class="question">
 379 <p>Compiling LLVM with GCC succeeds, but the resulting tools do not work, what
 380    can be wrong?</p>
 381 </div>
 382
 383 <div class="answer">
 384 <p>Several versions of GCC have shown a weakness in miscompiling the LLVM
 385    codebase. Please consult your compiler version (<tt>gcc --version</tt>) to
 386    find out whether it is <a href="GettingStarted.html#brokengcc">broken</a>.
 387    If so, your only option is to upgrade GCC to a known good version.</p>
 388 </div>
 389
 390 <div class="question">
 391 <p>After Subversion update, rebuilding gives the error "No rule to make
 392    target".</p>
 393 </div>
 394
 395 <div class="answer">
 396 <p>If the error is of the form:</p>
 397
 398 <pre class="doc_code">
 399 gmake[2]: *** No rule to make target `/path/to/somefile', needed by
 400 `/path/to/another/file.d'.<br>
 401 Stop.
 402 </pre>
 403
 404 <p>This may occur anytime files are moved within the Subversion repository or
 405    removed entirely.  In this case, the best solution is to erase all
 406    <tt>.d</tt> files, which list dependencies for source files, and rebuild:</p>
 407
 408 <pre class="doc_code">
 409 % cd $LLVM_OBJ_DIR
 410 % rm -f `find . -name \*\.d`
 411 % gmake
 412 </pre>
 413
 414 <p>In other cases, it may be necessary to run <tt>make clean</tt> before
 415    rebuilding.</p>
 416 </div>
 417
 418 <div class="question">
 419 <p><a name="llvmc">The <tt>llvmc</tt> program gives me errors/doesn't
 420    work.</a></p>
 421 </div>
 422
 423 <div class="answer">
 424 <p><tt>llvmc</tt> is experimental and isn't really supported. We suggest
 425    using <tt>llvm-gcc</tt> instead.</p>
 426 </div>
 427
 428 <div class="question">
 429 <p><a name="srcdir-objdir">When I compile LLVM-GCC with srcdir == objdir, it
 430    fails. Why?</a></p>
 431 </div>
 432
 433 <div class="answer">
 434 <p>The <tt>GNUmakefile</tt> in the top-level directory of LLVM-GCC is a special
 435    <tt>Makefile</tt> used by Apple to invoke the <tt>build_gcc</tt> script after
 436    setting up a special environment. This has the unforunate side-effect that
 437    trying to build LLVM-GCC with srcdir == objdir in a "non-Apple way" invokes
 438    the <tt>GNUmakefile</tt> instead of <tt>Makefile</tt>. Because the
 439    environment isn't set up correctly to do this, the build fails.</p>
 440
 441 <p>People not building LLVM-GCC the "Apple way" need to build LLVM-GCC with
 442    srcdir != objdir, or simply remove the GNUmakefile entirely.</p>
 443
 444 <p>We regret the inconvenience.</p>
 445 </div>
 446
 447 <!-- *********************************************************************** -->
 448 <div class="doc_section"><a name="felangs">Source Languages</a></div>
 449
 450 <div class="question">
 451 <p><a name="langs">What source languages are supported?</a></p>
 452 </div>
 453
 454 <div class="answer">
 455 <p>LLVM currently has full support for C and C++ source languages. These are
 456    available through a special version of GCC that LLVM calls the
 457    <a href="#cfe">C Front End</a></p>
 458
 459 <p>There is an incomplete version of a Java front end available in the
 460    <tt>java</tt> module. There is no documentation on this yet so you'll need to
 461    download the code, compile it, and try it.</p>
 462
 463 <p>The PyPy developers are working on integrating LLVM into the PyPy backend so
 464    that PyPy language can translate to LLVM.</p>
 465 </div>
 466
 467 <div class="question">
 468 <p><a name="langirgen">I'd like to write a self-hosting LLVM compiler. How
 469    should I interface with the LLVM middle-end optimizers and back-end code
 470    generators?</a></p>
 471 </div>
 472
 473 <div class="answer">
 474 <p>Your compiler front-end will communicate with LLVM by creating a module in
 475    the LLVM intermediate representation (IR) format. Assuming you want to write
 476    your language's compiler in the language itself (rather than C++), there are
 477    3 major ways to tackle generating LLVM IR from a front-end:</p>
 478
 479 <ul>
 480   <li><strong>Call into the LLVM libraries code using your language's FFI
 481       (foreign function interface).</strong>
 482
 483     <ul>
 484       <li><em>for:</em> best tracks changes to the LLVM IR, .ll syntax, and .bc
 485           format</li>
 486
 487       <li><em>for:</em> enables running LLVM optimization passes without a
 488           emit/parse overhead</li>
 489
 490       <li><em>for:</em> adapts well to a JIT context</li>
 491
 492       <li><em>against:</em> lots of ugly glue code to write</li>
 493     </ul></li>
 494
 495   <li>  <strong>Emit LLVM assembly from your compiler's native language.</strong>
 496     <ul>
 497       <li><em>for:</em> very straightforward to get started</li>
 498
 499       <li><em>against:</em> the .ll parser is slower than the bitcode reader
 500           when interfacing to the middle end</li>
 501
 502       <li><em>against:</em> you'll have to re-engineer the LLVM IR object model
 503           and asm writer in your language</li>
 504
 505       <li><em>against:</em> it may be harder to track changes to the IR</li>
 506     </ul></li>
 507
 508   <li><strong>Emit LLVM bitcode from your compiler's native language.</strong>
 509
 510     <ul>
 511       <li><em>for:</em> can use the more-efficient bitcode reader when
 512           interfacing to the middle end</li>
 513
 514       <li><em>against:</em> you'll have to re-engineer the LLVM IR object
 515           model and bitcode writer in your language</li>
 516
 517       <li><em>against:</em> it may be harder to track changes to the IR</li>
 518     </ul></li>
 519 </ul>
 520
 521 <p>If you go with the first option, the C bindings in include/llvm-c should help
 522    a lot, since most languages have strong support for interfacing with C. The
 523    most common hurdle with calling C from managed code is interfacing with the
 524    garbage collector. The C interface was designed to require very little memory
 525    management, and so is straightforward in this regard.</p>
 526 </div>
 527
 528 <div class="question">
 529 <p><a name="langhlsupp">What support is there for a higher level source language
 530    constructs for building a compiler?</a></p>
 531 </div>
 532
 533 <div class="answer">
 534 <p>Currently, there isn't much. LLVM supports an intermediate representation
 535    which is useful for code representation but will not support the high level
 536    (abstract syntax tree) representation needed by most compilers. There are no
 537    facilities for lexical nor semantic analysis. There is, however, a <i>mostly
 538    implemented</i> configuration-driven
 539    <a href="CompilerDriver.html">compiler driver</a> which simplifies the task
 540    of running optimizations, linking, and executable generation.</p>
 541 </div>
 542
 543 <div class="question">
 544 <p><a name="getelementptr">I don't understand the GetElementPtr
 545    instruction. Help!</a></p>
 546 </div>
 547
 548 <div class="answer">
 549 <p>See <a href="GetElementPtr.html">The Often Misunderstood GEP
 550    Instruction</a>.</p>
 551 </div>
 552
 553 <!-- *********************************************************************** -->
 554 <div class="doc_section">
 555   <a name="cfe">Using the GCC Front End</a>
 556 </div>
 557
 558 <div class="question">
 559 <p>When I compile software that uses a configure script, the configure script
 560    thinks my system has all of the header files and libraries it is testing for.
 561    How do I get configure to work correctly?</p>
 562 </div>
 563
 564 <div class="answer">
 565 <p>The configure script is getting things wrong because the LLVM linker allows
 566    symbols to be undefined at link time (so that they can be resolved during JIT
 567    or translation to the C back end).  That is why configure thinks your system
 568    "has everything."</p>
 569
 570 <p>To work around this, perform the following steps:</p>
 571
 572 <ol>
 573   <li>Make sure the CC and CXX environment variables contains the full path to
 574       the LLVM GCC front end.</li>
 575
 576   <li>Make sure that the regular C compiler is first in your PATH. </li>
 577
 578   <li>Add the string "-Wl,-native" to your CFLAGS environment variable.</li>
 579 </ol>
 580
 581 <p>This will allow the <tt>llvm-ld</tt> linker to create a native code
 582    executable instead of shell script that runs the JIT.  Creating native code
 583    requires standard linkage, which in turn will allow the configure script to
 584    find out if code is not linking on your system because the feature isn't
 585    available on your system.</p>
 586 </div>
 587
 588 <div class="question">
 589 <p>When I compile code using the LLVM GCC front end, it complains that it cannot
 590    find libcrtend.a.
 591 </p>
 592 </div>
 593
 594 <div class="answer">
 595 <p>The only way this can happen is if you haven't installed the runtime
 596    library. To correct this, do:</p>
 597
 598 <pre class="doc_code">
 599 % cd llvm/runtime
 600 % make clean ; make install-bytecode
 601 </pre>
 602 </div>
 603
 604 <div class="question">
 605 <p>How can I disable all optimizations when compiling code using the LLVM GCC
 606    front end?</p>
 607 </div>
 608
 609 <div class="answer">
 610 <p>Passing "-Wa,-disable-opt -Wl,-disable-opt" will disable *all* cleanup and
 611    optimizations done at the llvm level, leaving you with the truly horrible
 612    code that you desire.</p>
 613 </div>
 614
 615
 616 <div class="question">
 617 <p><a name="translatecxx">Can I use LLVM to convert C++ code to C code?</a></p>
 618 </div>
 619
 620 <div class="answer">
 621 <p>Yes, you can use LLVM to convert code from any language LLVM supports to C.
 622    Note that the generated C code will be very low level (all loops are lowered
 623    to gotos, etc) and not very pretty (comments are stripped, original source
 624    formatting is totally lost, variables are renamed, expressions are
 625    regrouped), so this may not be what you're looking for. Also, there are
 626    several limitations noted below.<p>
 627
 628 <p>Use commands like this:</p>
 629
 630 <ol>
 631   <li><p>Compile your program as normal with llvm-g++:</p>
 632
 633 <pre class="doc_code">
 634 % llvm-g++ x.cpp -o program
 635 </pre>
 636
 637       <p>or:</p>
 638
 639 <pre class="doc_code">
 640 % llvm-g++ a.cpp -c
 641 % llvm-g++ b.cpp -c
 642 % llvm-g++ a.o b.o -o program
 643 </pre>
 644
 645       <p>With llvm-gcc3, this will generate program and program.bc.  The .bc
 646          file is the LLVM version of the program all linked together.</p></li>
 647
 648   <li><p>Convert the LLVM code to C code, using the LLC tool with the C
 649       backend:</p>
 650
 651 <pre class="doc_code">
 652 % llc -march=c program.bc -o program.c
 653 </pre></li>
 654
 655   <li><p>Finally, compile the C file:</p>
 656
 657 <pre class="doc_code">
 658 % cc x.c
 659 </pre></li>
 660
 661 </ol>
 662
 663 <p>Using LLVM does not eliminate the need for C++ library support.  If you use
 664    the llvm-g++ front-end, the generated code will depend on g++'s C++ support
 665    libraries in the same way that code generated from g++ would.  If you use
 666    another C++ front-end, the generated code will depend on whatever library
 667    that front-end would normally require.</p>
 668
 669 <p>If you are working on a platform that does not provide any C++ libraries, you
 670    may be able to manually compile libstdc++ to LLVM bitcode, statically link it
 671    into your program, then use the commands above to convert the whole result
 672    into C code.  Alternatively, you might compile the libraries and your
 673    application into two different chunks of C code and link them.</p>
 674
 675 <p>Note that, by default, the C back end does not support exception handling.
 676    If you want/need it for a certain program, you can enable it by passing
 677    "-enable-correct-eh-support" to the llc program.  The resultant code will use
 678    setjmp/longjmp to implement exception support that is relatively slow, and
 679    not C++-ABI-conforming on most platforms, but otherwise correct.</p>
 680
 681 <p>Also, there are a number of other limitations of the C backend that cause it
 682    to produce code that does not fully conform to the C++ ABI on most
 683    platforms. Some of the C++ programs in LLVM's test suite are known to fail
 684    when compiled with the C back end because of ABI incompatiblities with
 685    standard C++ libraries.</p>
 686 </div>
 687
 688 <div class="question">
 689 <p><a name="platformindependent">Can I compile C or C++ code to
 690    platform-independent LLVM bitcode?</a></p>
 691 </div>
 692
 693 <div class="answer">
 694 <p>No. C and C++ are inherently platform-dependent languages. The most obvious
 695    example of this is the preprocessor. A very common way that C code is made
 696    portable is by using the preprocessor to include platform-specific code. In
 697    practice, information about other platforms is lost after preprocessing, so
 698    the result is inherently dependent on the platform that the preprocessing was
 699    targetting.</p>
 700
 701 <p>Another example is <tt>sizeof</tt>. It's common for <tt>sizeof(long)</tt> to
 702    vary between platforms. In most C front-ends, <tt>sizeof</tt> is expanded to
 703    a constant immediately, thus hard-wiring a platform-specific detail.</p>
 704
 705 <p>Also, since many platforms define their ABIs in terms of C, and since LLVM is
 706    lower-level than C, front-ends currently must emit platform-specific IR in
 707    order to have the result conform to the platform ABI.</p>
 708 </div>
 709
 710 <!-- *********************************************************************** -->
 711 <div class="doc_section">
 712   <a name="cfe_code">Questions about code generated by the GCC front-end</a>
 713 </div>
 714
 715 <div class="question">
 716 <p><a name="iosinit">What is this <tt>llvm.global_ctors</tt> and
 717    <tt>_GLOBAL__I__tmp_webcompile...</tt> stuff that happens when I <tt>#include
 718    &lt;iostream&gt;</tt>?</a></p>
 719 </div>
 720
 721 <div class="answer">
 722 <p>If you <tt>#include</tt> the <tt>&lt;iostream&gt;</tt> header into a C++
 723    translation unit, the file will probably use
 724    the <tt>std::cin</tt>/<tt>std::cout</tt>/... global objects.  However, C++
 725    does not guarantee an order of initialization between static objects in
 726    different translation units, so if a static ctor/dtor in your .cpp file
 727    used <tt>std::cout</tt>, for example, the object would not necessarily be
 728    automatically initialized before your use.</p>
 729
 730 <p>To make <tt>std::cout</tt> and friends work correctly in these scenarios, the
 731    STL that we use declares a static object that gets created in every
 732    translation unit that includes <tt>&lt;iostream&gt;</tt>.  This object has a
 733    static constructor and destructor that initializes and destroys the global
 734    iostream objects before they could possibly be used in the file.  The code
 735    that you see in the .ll file corresponds to the constructor and destructor
 736    registration code.
 737 </p>
 738
 739 <p>If you would like to make it easier to <b>understand</b> the LLVM code
 740    generated by the compiler in the demo page, consider using <tt>printf()</tt>
 741    instead of <tt>iostream</tt>s to print values.</p>
 742 </div>
 743
 744 <!--=========================================================================-->
 745
 746 <div class="question">
 747 <p><a name="codedce">Where did all of my code go??</a></p>
 748 </div>
 749
 750 <div class="answer">
 751 <p>If you are using the LLVM demo page, you may often wonder what happened to
 752    all of the code that you typed in.  Remember that the demo script is running
 753    the code through the LLVM optimizers, so if your code doesn't actually do
 754    anything useful, it might all be deleted.</p>
 755
 756 <p>To prevent this, make sure that the code is actually needed.  For example, if
 757    you are computing some expression, return the value from the function instead
 758    of leaving it in a local variable.  If you really want to constrain the
 759    optimizer, you can read from and assign to <tt>volatile</tt> global
 760    variables.</p>
 761 </div>
 762
 763 <!--=========================================================================-->
 764
 765 <div class="question">
 766 <p><a name="undef">What is this "<tt>undef</tt>" thing that shows up in my
 767    code?</a></p>
 768 </div>
 769
 770 <div class="answer">
 771 <p><a href="LangRef.html#undef"><tt>undef</tt></a> is the LLVM way of
 772    representing a value that is not defined.  You can get these if you do not
 773    initialize a variable before you use it.  For example, the C function:</p>
 774
 775 <pre class="doc_code">
 776 int X() { int i; return i; }
 777 </pre>
 778
 779 <p>Is compiled to "<tt>ret i32 undef</tt>" because "<tt>i</tt>" never has a
 780    value specified for it.</p>
 781 </div>
 782
 783 <!-- *********************************************************************** -->
 784
 785 <hr>
 786 <address>
 787   <a href="http://jigsaw.w3.org/css-validator/check/referer"><img
 788   src="http://jigsaw.w3.org/css-validator/images/vcss-blue" alt="Valid CSS"></a>
 789   <a href="http://validator.w3.org/check/referer"><img
 790   src="http://www.w3.org/Icons/valid-html401-blue" alt="Valid HTML 4.01"></a>
 791
 792   <a href="http://llvm.org">LLVM Compiler Infrastructure</a><br>
 793   Last modified: $Date$
 794 </address>
 795
 796 </body>
 797 </html>