docs/FAQ.html

   1 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN"
   2                       "http://www.w3.org/TR/html4/strict.dtd">
   3 <html>
   4 <head>
   5   <meta http-equiv="Content-Type" content="text/html; charset=utf-8">
   6   <title>LLVM: Frequently Asked Questions</title>
   7   <style type="text/css">
   8     @import url("llvm.css");
   9     .question { font-weight: bold }
  10     .answer   { margin-left: 2em  }
  11   </style>
  12 </head>
  13 <body>
  14
  15 <div class="doc_title">
  16   LLVM: Frequently Asked Questions
  17 </div>
  18
  19 <ol>
  20   <li><a href="#license">License</a>
  21   <ol>
  22     <li>Why are the LLVM source code and the front-end distributed under
  23         different licenses?</li>
  24
  25     <li>Does the University of Illinois Open Source License really qualify as an
  26        "open source" license?</li>
  27
  28     <li>Can I modify LLVM source code and redistribute the modified source?</li>
  29
  30     <li>Can I modify LLVM source code and redistribute binaries or other tools
  31         based on it, without redistributing the source?</li>
  32   </ol></li>
  33
  34   <li><a href="#source">Source code</a>
  35   <ol>
  36     <li>In what language is LLVM written?</li>
  37
  38     <li>How portable is the LLVM source code?</li>
  39   </ol></li>
  40
  41   <li><a href="#build">Build Problems</a>
  42   <ol>
  43     <li>When I run configure, it finds the wrong C compiler.</li>
  44
  45     <li>The <tt>configure</tt> script finds the right C compiler, but it uses
  46         the LLVM linker from a previous build.  What do I do?</li>
  47
  48     <li>When creating a dynamic library, I get a strange GLIBC error.</li>
  49
  50     <li>I've updated my source tree from Subversion, and now my build is trying
  51         to use a file/directory that doesn't exist.</li>
  52
  53     <li>I've modified a Makefile in my source tree, but my build tree keeps
  54         using the old version.  What do I do?</li>
  55
  56     <li>I've upgraded to a new version of LLVM, and I get strange build
  57         errors.</li>
  58
  59     <li>I've built LLVM and am testing it, but the tests freeze.</li>
  60
  61     <li>Why do test results differ when I perform different types of
  62         builds?</li>
  63
  64     <li>Compiling LLVM with GCC 3.3.2 fails, what should I do?</li>
  65
  66     <li>Compiling LLVM with GCC succeeds, but the resulting tools do not work,
  67         what can be wrong?</li>
  68
  69     <li>When I use the test suite, all of the C Backend tests fail.  What is
  70         wrong?</li>
  71
  72     <li>After Subversion update, rebuilding gives the error "No rule to make
  73         target".</li>
  74
  75     <li><a href="#llvmc">The <tt>llvmc</tt> program gives me errors/doesn't
  76         work.</a></li>
  77
  78     <li><a href="#srcdir-objdir">When I compile LLVM-GCC with srcdir == objdir,
  79         it fails. Why?</a></li>
  80   </ol></li>
  81
  82   <li><a href="#felangs">Source Languages</a>
  83   <ol>
  84     <li><a href="#langs">What source languages are supported?</a></li>
  85
  86     <li><a href="#langirgen">I'd like to write a self-hosting LLVM compiler. How
  87         should I interface with the LLVM middle-end optimizers and back-end code
  88         generators?</a></li>
  89
  90     <li><a href="#langhlsupp">What support is there for higher level source
  91         language constructs for building a compiler?</a></li>
  92
  93     <li><a href="GetElementPtr.html">I don't understand the GetElementPtr
  94       instruction. Help!</a></li>
  95   </ol>
  96
  97   <li><a href="#cfe">Using the GCC Front End</a>
  98   <ol>
  99     <li>When I compile software that uses a configure script, the configure
 100         script thinks my system has all of the header files and libraries it is
 101         testing for.  How do I get configure to work correctly?</li>
 102
 103     <li>When I compile code using the LLVM GCC front end, it complains that it
 104         cannot find libcrtend.a?</li>
 105
 106     <li>How can I disable all optimizations when compiling code using the LLVM
 107         GCC front end?</li>
 108
 109     <li><a href="#translatecxx">Can I use LLVM to convert C++ code to C
 110         code?</a></li>
 111
 112     <li><a href="#platformindependent">Can I compile C or C++ code to
 113         platform-independent LLVM bitcode?</a></li>
 114   </ol>
 115   </li>
 116
 117   <li><a href="#cfe_code">Questions about code generated by the GCC front-end</a>
 118   <ol>
 119      <li><a href="#iosinit">What is this <tt>llvm.global_ctors</tt> and
 120           <tt>_GLOBAL__I__tmp_webcompile...</tt> stuff that happens when I
 121           #include &lt;iostream&gt;?</a></li>
 122
 123      <li><a href="#codedce">Where did all of my code go??</a></li>
 124
 125      <li><a href="#undef">What is this "<tt>undef</tt>" thing that shows up in
 126          my code?</a></li>
 127
 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 <div class="doc_section">
 142   <a name="license">License</a>
 143 </div>
 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 <div class="doc_section">
 193   <a name="source">Source Code</a>
 194 </div>
 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 <div class="doc_section">
 231   <a name="build">Build Problems</a>
 232 </div>
 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 <div class="doc_section"><a name="felangs">Source Languages</a></div>
 453
 454 <div class="question">
 455 <p><a name="langs">What source languages are supported?</a></p>
 456 </div>
 457
 458 <div class="answer">
 459 <p>LLVM currently has full support for C and C++ source languages. These are
 460    available through a special version of GCC that LLVM calls the
 461    <a href="#cfe">C Front End</a></p>
 462
 463 <p>There is an incomplete version of a Java front end available in the
 464    <tt>java</tt> module. There is no documentation on this yet so you'll need to
 465    download the code, compile it, and try it.</p>
 466
 467 <p>The PyPy developers are working on integrating LLVM into the PyPy backend so
 468    that PyPy language can translate to LLVM.</p>
 469 </div>
 470
 471 <div class="question">
 472 <p><a name="langirgen">I'd like to write a self-hosting LLVM compiler. How
 473    should I interface with the LLVM middle-end optimizers and back-end code
 474    generators?</a></p>
 475 </div>
 476
 477 <div class="answer">
 478 <p>Your compiler front-end will communicate with LLVM by creating a module in
 479    the LLVM intermediate representation (IR) format. Assuming you want to write
 480    your language's compiler in the language itself (rather than C++), there are
 481    3 major ways to tackle generating LLVM IR from a front-end:</p>
 482
 483 <ul>
 484   <li><strong>Call into the LLVM libraries code using your language's FFI
 485       (foreign function interface).</strong>
 486
 487     <ul>
 488       <li><em>for:</em> best tracks changes to the LLVM IR, .ll syntax, and .bc
 489           format</li>
 490
 491       <li><em>for:</em> enables running LLVM optimization passes without a
 492           emit/parse overhead</li>
 493
 494       <li><em>for:</em> adapts well to a JIT context</li>
 495
 496       <li><em>against:</em> lots of ugly glue code to write</li>
 497     </ul></li>
 498
 499   <li>  <strong>Emit LLVM assembly from your compiler's native language.</strong>
 500     <ul>
 501       <li><em>for:</em> very straightforward to get started</li>
 502
 503       <li><em>against:</em> the .ll parser is slower than the bitcode reader
 504           when interfacing to the middle end</li>
 505
 506       <li><em>against:</em> you'll have to re-engineer the LLVM IR object model
 507           and asm writer in your language</li>
 508
 509       <li><em>against:</em> it may be harder to track changes to the IR</li>
 510     </ul></li>
 511
 512   <li><strong>Emit LLVM bitcode from your compiler's native language.</strong>
 513
 514     <ul>
 515       <li><em>for:</em> can use the more-efficient bitcode reader when
 516           interfacing to the middle end</li>
 517
 518       <li><em>against:</em> you'll have to re-engineer the LLVM IR object
 519           model and bitcode writer in your language</li>
 520
 521       <li><em>against:</em> it may be harder to track changes to the IR</li>
 522     </ul></li>
 523 </ul>
 524
 525 <p>If you go with the first option, the C bindings in include/llvm-c should help
 526    a lot, since most languages have strong support for interfacing with C. The
 527    most common hurdle with calling C from managed code is interfacing with the
 528    garbage collector. The C interface was designed to require very little memory
 529    management, and so is straightforward in this regard.</p>
 530 </div>
 531
 532 <div class="question">
 533 <p><a name="langhlsupp">What support is there for a higher level source language
 534    constructs for building a compiler?</a></p>
 535 </div>
 536
 537 <div class="answer">
 538 <p>Currently, there isn't much. LLVM supports an intermediate representation
 539    which is useful for code representation but will not support the high level
 540    (abstract syntax tree) representation needed by most compilers. There are no
 541    facilities for lexical nor semantic analysis. There is, however, a <i>mostly
 542    implemented</i> configuration-driven
 543    <a href="CompilerDriver.html">compiler driver</a> which simplifies the task
 544    of running optimizations, linking, and executable generation.</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 <!-- *********************************************************************** -->
 558 <div class="doc_section">
 559   <a name="cfe">Using the GCC Front End</a>
 560 </div>
 561
 562 <div class="question">
 563 <p>When I compile software that uses a configure script, the configure script
 564    thinks my system has all of the header files and libraries it is testing for.
 565    How do I get configure to work correctly?</p>
 566 </div>
 567
 568 <div class="answer">
 569 <p>The configure script is getting things wrong because the LLVM linker allows
 570    symbols to be undefined at link time (so that they can be resolved during JIT
 571    or translation to the C back end).  That is why configure thinks your system
 572    "has everything."</p>
 573
 574 <p>To work around this, perform the following steps:</p>
 575
 576 <ol>
 577   <li>Make sure the CC and CXX environment variables contains the full path to
 578       the LLVM GCC front end.</li>
 579
 580   <li>Make sure that the regular C compiler is first in your PATH. </li>
 581
 582   <li>Add the string "-Wl,-native" to your CFLAGS environment variable.</li>
 583 </ol>
 584
 585 <p>This will allow the <tt>llvm-ld</tt> linker to create a native code
 586    executable instead of shell script that runs the JIT.  Creating native code
 587    requires standard linkage, which in turn will allow the configure script to
 588    find out if code is not linking on your system because the feature isn't
 589    available on your system.</p>
 590 </div>
 591
 592 <div class="question">
 593 <p>When I compile code using the LLVM GCC front end, it complains that it cannot
 594    find libcrtend.a.
 595 </p>
 596 </div>
 597
 598 <div class="answer">
 599 <p>The only way this can happen is if you haven't installed the runtime
 600    library. To correct this, do:</p>
 601
 602 <pre class="doc_code">
 603 % cd llvm/runtime
 604 % make clean ; make install-bytecode
 605 </pre>
 606 </div>
 607
 608 <div class="question">
 609 <p>How can I disable all optimizations when compiling code using the LLVM GCC
 610    front end?</p>
 611 </div>
 612
 613 <div class="answer">
 614 <p>Passing "-Wa,-disable-opt -Wl,-disable-opt" will disable *all* cleanup and
 615    optimizations done at the llvm level, leaving you with the truly horrible
 616    code that you desire.</p>
 617 </div>
 618
 619
 620 <div class="question">
 621 <p><a name="translatecxx">Can I use LLVM to convert C++ code to C code?</a></p>
 622 </div>
 623
 624 <div class="answer">
 625 <p>Yes, you can use LLVM to convert code from any language LLVM supports to C.
 626    Note that the generated C code will be very low level (all loops are lowered
 627    to gotos, etc) and not very pretty (comments are stripped, original source
 628    formatting is totally lost, variables are renamed, expressions are
 629    regrouped), so this may not be what you're looking for. Also, there are
 630    several limitations noted below.<p>
 631
 632 <p>Use commands like this:</p>
 633
 634 <ol>
 635   <li><p>Compile your program with llvm-g++:</p>
 636
 637 <pre class="doc_code">
 638 % llvm-g++ -emit-llvm x.cpp -o program.bc -c
 639 </pre>
 640
 641       <p>or:</p>
 642
 643 <pre class="doc_code">
 644 % llvm-g++ a.cpp -c -emit-llvm
 645 % llvm-g++ b.cpp -c -emit-llvm
 646 % llvm-ld a.o b.o -o program
 647 </pre>
 648
 649    <p>This will generate program and program.bc.  The .bc
 650       file is the LLVM version of the program all linked together.</p></li>
 651
 652   <li><p>Convert the LLVM code to C code, using the LLC tool with the C
 653       backend:</p>
 654
 655 <pre class="doc_code">
 656 % llc -march=c program.bc -o program.c
 657 </pre></li>
 658
 659   <li><p>Finally, compile the C file:</p>
 660
 661 <pre class="doc_code">
 662 % cc x.c -lstdc++
 663 </pre></li>
 664
 665 </ol>
 666
 667 <p>Using LLVM does not eliminate the need for C++ library support.  If you use
 668    the llvm-g++ front-end, the generated code will depend on g++'s C++ support
 669    libraries in the same way that code generated from g++ would.  If you use
 670    another C++ front-end, the generated code will depend on whatever library
 671    that front-end would normally require.</p>
 672
 673 <p>If you are working on a platform that does not provide any C++ libraries, you
 674    may be able to manually compile libstdc++ to LLVM bitcode, statically link it
 675    into your program, then use the commands above to convert the whole result
 676    into C code.  Alternatively, you might compile the libraries and your
 677    application into two different chunks of C code and link them.</p>
 678
 679 <p>Note that, by default, the C back end does not support exception handling.
 680    If you want/need it for a certain program, you can enable it by passing
 681    "-enable-correct-eh-support" to the llc program.  The resultant code will use
 682    setjmp/longjmp to implement exception support that is relatively slow, and
 683    not C++-ABI-conforming on most platforms, but otherwise correct.</p>
 684
 685 <p>Also, there are a number of other limitations of the C backend that cause it
 686    to produce code that does not fully conform to the C++ ABI on most
 687    platforms. Some of the C++ programs in LLVM's test suite are known to fail
 688    when compiled with the C back end because of ABI incompatibilities with
 689    standard C++ libraries.</p>
 690 </div>
 691
 692 <div class="question">
 693 <p><a name="platformindependent">Can I compile C or C++ code to
 694    platform-independent LLVM bitcode?</a></p>
 695 </div>
 696
 697 <div class="answer">
 698 <p>No. C and C++ are inherently platform-dependent languages. The most obvious
 699    example of this is the preprocessor. A very common way that C code is made
 700    portable is by using the preprocessor to include platform-specific code. In
 701    practice, information about other platforms is lost after preprocessing, so
 702    the result is inherently dependent on the platform that the preprocessing was
 703    targeting.</p>
 704
 705 <p>Another example is <tt>sizeof</tt>. It's common for <tt>sizeof(long)</tt> to
 706    vary between platforms. In most C front-ends, <tt>sizeof</tt> is expanded to
 707    a constant immediately, thus hard-wiring a platform-specific detail.</p>
 708
 709 <p>Also, since many platforms define their ABIs in terms of C, and since LLVM is
 710    lower-level than C, front-ends currently must emit platform-specific IR in
 711    order to have the result conform to the platform ABI.</p>
 712 </div>
 713
 714 <!-- *********************************************************************** -->
 715 <div class="doc_section">
 716   <a name="cfe_code">Questions about code generated by the GCC front-end</a>
 717 </div>
 718
 719 <div class="question">
 720 <p><a name="iosinit">What is this <tt>llvm.global_ctors</tt> and
 721    <tt>_GLOBAL__I__tmp_webcompile...</tt> stuff that happens when I <tt>#include
 722    &lt;iostream&gt;</tt>?</a></p>
 723 </div>
 724
 725 <div class="answer">
 726 <p>If you <tt>#include</tt> the <tt>&lt;iostream&gt;</tt> header into a C++
 727    translation unit, the file will probably use
 728    the <tt>std::cin</tt>/<tt>std::cout</tt>/... global objects.  However, C++
 729    does not guarantee an order of initialization between static objects in
 730    different translation units, so if a static ctor/dtor in your .cpp file
 731    used <tt>std::cout</tt>, for example, the object would not necessarily be
 732    automatically initialized before your use.</p>
 733
 734 <p>To make <tt>std::cout</tt> and friends work correctly in these scenarios, the
 735    STL that we use declares a static object that gets created in every
 736    translation unit that includes <tt>&lt;iostream&gt;</tt>.  This object has a
 737    static constructor and destructor that initializes and destroys the global
 738    iostream objects before they could possibly be used in the file.  The code
 739    that you see in the .ll file corresponds to the constructor and destructor
 740    registration code.
 741 </p>
 742
 743 <p>If you would like to make it easier to <b>understand</b> the LLVM code
 744    generated by the compiler in the demo page, consider using <tt>printf()</tt>
 745    instead of <tt>iostream</tt>s to print values.</p>
 746 </div>
 747
 748 <!--=========================================================================-->
 749
 750 <div class="question">
 751 <p><a name="codedce">Where did all of my code go??</a></p>
 752 </div>
 753
 754 <div class="answer">
 755 <p>If you are using the LLVM demo page, you may often wonder what happened to
 756    all of the code that you typed in.  Remember that the demo script is running
 757    the code through the LLVM optimizers, so if your code doesn't actually do
 758    anything useful, it might all be deleted.</p>
 759
 760 <p>To prevent this, make sure that the code is actually needed.  For example, if
 761    you are computing some expression, return the value from the function instead
 762    of leaving it in a local variable.  If you really want to constrain the
 763    optimizer, you can read from and assign to <tt>volatile</tt> global
 764    variables.</p>
 765 </div>
 766
 767 <!--=========================================================================-->
 768
 769 <div class="question">
 770 <p><a name="undef">What is this "<tt>undef</tt>" thing that shows up in my
 771    code?</a></p>
 772 </div>
 773
 774 <div class="answer">
 775 <p><a href="LangRef.html#undef"><tt>undef</tt></a> is the LLVM way of
 776    representing a value that is not defined.  You can get these if you do not
 777    initialize a variable before you use it.  For example, the C function:</p>
 778
 779 <pre class="doc_code">
 780 int X() { int i; return i; }
 781 </pre>
 782
 783 <p>Is compiled to "<tt>ret i32 undef</tt>" because "<tt>i</tt>" never has a
 784    value specified for it.</p>
 785 </div>
 786
 787 <!--=========================================================================-->
 788
 789 <div class="question">
 790 <p><a name="callconvwrong">Why does instcombine + simplifycfg turn
 791    a call to a function with a mismatched calling convention into "unreachable"?
 792    Why not make the verifier reject it?</a></p>
 793 </div>
 794
 795 <div class="answer">
 796 <p>This is a common problem run into by authors of front-ends that are using
 797 custom calling conventions: you need to make sure to set the right calling
 798 convention on both the function and on each call to the function.  For example,
 799 this code:</p>
 800
 801 <pre class="doc_code">
 802 define fastcc void @foo() {
 803         ret void
 804 }
 805 define void @bar() {
 806         call void @foo()
 807         ret void
 808 }
 809 </pre>
 810
 811 <p>Is optimized to:</p>
 812
 813 <pre class="doc_code">
 814 define fastcc void @foo() {
 815         ret void
 816 }
 817 define void @bar() {
 818         unreachable
 819 }
 820 </pre>
 821
 822 <p>... with "opt -instcombine -simplifycfg".  This often bites people because
 823 "all their code disappears".  Setting the calling convention on the caller and
 824 callee is required for indirect calls to work, so people often ask why not make
 825 the verifier reject this sort of thing.</p>
 826
 827 <p>The answer is that this code has undefined behavior, but it is not illegal.
 828 If we made it illegal, then every transformation that could potentially create
 829 this would have to ensure that it doesn't, and there is valid code that can
 830 create this sort of construct (in dead code).  The sorts of things that can
 831 cause this to happen are fairly contrived, but we still need to accept them.
 832 Here's an example:</p>
 833
 834 <pre class="doc_code">
 835 define fastcc void @foo() {
 836         ret void
 837 }
 838 define internal void @bar(void()* %FP, i1 %cond) {
 839         br i1 %cond, label %T, label %F
 840 T:
 841         call void %FP()
 842         ret void
 843 F:
 844         call fastcc void %FP()
 845         ret void
 846 }
 847 define void @test() {
 848         %X = or i1 false, false
 849         call void @bar(void()* @foo, i1 %X)
 850         ret void
 851 }
 852 </pre>
 853
 854 <p>In this example, "test" always passes @foo/false into bar, which ensures that
 855    it is dynamically called with the right calling conv (thus, the code is
 856    perfectly well defined).  If you run this through the inliner, you get this
 857    (the explicit "or" is there so that the inliner doesn't dead code eliminate
 858    a bunch of stuff):
 859 </p>
 860
 861 <pre class="doc_code">
 862 define fastcc void @foo() {
 863         ret void
 864 }
 865 define void @test() {
 866         %X = or i1 false, false
 867         br i1 %X, label %T.i, label %F.i
 868 T.i:
 869         call void @foo()
 870         br label %bar.exit
 871 F.i:
 872         call fastcc void @foo()
 873         br label %bar.exit
 874 bar.exit:
 875         ret void
 876 }
 877 </pre>
 878
 879 <p>Here you can see that the inlining pass made an undefined call to @foo with
 880   the wrong calling convention.  We really don't want to make the inliner have
 881   to know about this sort of thing, so it needs to be valid code.  In this case,
 882   dead code elimination can trivially remove the undefined code.  However, if %X
 883   was an input argument to @test, the inliner would produce this:
 884 </p>
 885
 886 <pre class="doc_code">
 887 define fastcc void @foo() {
 888         ret void
 889 }
 890
 891 define void @test(i1 %X) {
 892         br i1 %X, label %T.i, label %F.i
 893 T.i:
 894         call void @foo()
 895         br label %bar.exit
 896 F.i:
 897         call fastcc void @foo()
 898         br label %bar.exit
 899 bar.exit:
 900         ret void
 901 }
 902 </pre>
 903
 904 <p>The interesting thing about this is that %X <em>must</em> be false for the
 905 code to be well-defined, but no amount of dead code elimination will be able to
 906 delete the broken call as unreachable.  However, since instcombine/simplifycfg
 907 turns the undefined call into unreachable, we end up with a branch on a
 908 condition that goes to unreachable: a branch to unreachable can never happen, so
 909 "-inline -instcombine -simplifycfg" is able to produce:</p>
 910
 911 <pre class="doc_code">
 912 define fastcc void @foo() {
 913         ret void
 914 }
 915 define void @test(i1 %X) {
 916 F.i:
 917         call fastcc void @foo()
 918         ret void
 919 }
 920 </pre>
 921
 922 </div>
 923
 924 <!-- *********************************************************************** -->
 925
 926 <hr>
 927 <address>
 928   <a href="http://jigsaw.w3.org/css-validator/check/referer"><img
 929   src="http://jigsaw.w3.org/css-validator/images/vcss-blue" alt="Valid CSS"></a>
 930   <a href="http://validator.w3.org/check/referer"><img
 931   src="http://www.w3.org/Icons/valid-html401-blue" alt="Valid HTML 4.01"></a>
 932
 933   <a href="http://llvm.org">LLVM Compiler Infrastructure</a><br>
 934   Last modified: $Date$
 935 </address>
 936
 937 </body>
 938 </html>