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