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