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