Home | History | Annotate | Download | only in docs
      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>
    941