some random notes.

[oota-llvm.git] / docs / FAQ.html

diff --git a/docs/FAQ.html b/docs/FAQ.html
index ea2f802d1dd17f2bac314d4fd1e7d588777196cd..2d96195129a2194905ac69973e045bd91eedd322 100644 (file)
--- a/docs/FAQ.html
+++ b/docs/FAQ.html
@@ -59,6 +59,9 @@
   <li><a href="#felangs">Source Languages</a>
   <ol>
     <li><a href="#langs">What source languages are supported?</a></li>
+    <li><a href="#langirgen">I'd like to write a self-hosting LLVM compiler. How
+      should I interface with the LLVM middle-end optimizers and back-end code 
+      generators?</a></li>
     <li><a href="#langhlsupp">What support is there for higher level source
       language constructs for building a compiler?</a></li>
     <li><a href="GetElementPtr.html">I don't understand the GetElementPtr
@@ -82,7 +85,7 @@
     How can I disable all optimizations when compiling code using the LLVM GCC front end?
     </li>
 
-    <li><a href="#translatec++">Can I use LLVM to convert C++ code to C code?</a></li>
+    <li><a href="#translatecxx">Can I use LLVM to convert C++ code to C code?</a></li>
 
   </ol>
   </li>
@@ -139,7 +142,7 @@ Source Initiative (OSI).</p>
 <div class="answer">
 <p>Yes.  The modified source distribution must retain the copyright notice and
 follow the three bulletted conditions listed in the <a
-href="http://llvm.org/releases/1.3/LICENSE.TXT">LLVM license</a>.</p>
+href="http://llvm.org/releases/2.3/LICENSE.TXT">LLVM license</a>.</p>
 </div>
 
 <div class="question">
@@ -408,11 +411,61 @@ using <tt>llvm-gcc</tt> instead.</p>
   <p>There is an incomplete version of a Java front end available in the
   <tt>java</tt> module. There is no documentation on this yet so
   you'll need to download the code, compile it, and try it.</p>
-  <p>In the <tt>stacker</tt> module is a compiler and runtime
-  library for the Stacker language, a "toy" language loosely based on Forth.</p>
   <p>The PyPy developers are working on integrating LLVM into the PyPy backend
   so that PyPy language can translate to LLVM.</p>
 </div>
+
+<div class="question"><p><a name="langirgen">
+  I'd like to write a self-hosting LLVM compiler. How should I interface with 
+  the LLVM middle-end optimizers and back-end code generators?
+</a></p></div>
+<div class="answer">
+  <p>Your compiler front-end will communicate with LLVM by creating a module in
+     the LLVM intermediate representation (IR) format. Assuming you want to 
+     write your language's compiler in the language itself (rather than C++), 
+     there are 3 major ways to tackle generating LLVM IR from a front-end:</p>
+  <ul>
+    <li>
+      <strong>Call into the LLVM libraries code using your language's FFI 
+              (foreign function interface).</strong>
+      <ul>
+        <li><em>for:</em> best tracks changes to the LLVM IR, .ll syntax, 
+            and .bc format</li>
+        <li><em>for:</em> enables running LLVM optimization passes without a 
+            emit/parse overhead</li>
+        <li><em>for:</em> adapts well to a JIT context</li>
+        <li><em>against:</em> lots of ugly glue code to write</li>
+      </ul>
+    </li>
+    <li>
+      <strong>Emit LLVM assembly from your compiler's native language.</strong>
+      <ul>
+        <li><em>for:</em> very straightforward to get started</li>
+        <li><em>against:</em> the .ll parser is slower than the bitcode reader 
+            when interfacing to the middle end</li>
+        <li><em>against:</em> you'll have to re-engineer the LLVM IR object 
+            model and asm writer in your language</li>
+        <li><em>against:</em> it may be harder to track changes to the IR</li>
+      </ul>
+    </li>
+    <li>
+      <strong>Emit LLVM bitcode from your compiler's native language.</strong>
+      <ul>
+        <li><em>for:</em> can use the more-efficient bitcode reader when 
+            interfacing to the middle end</li>
+        <li><em>against:</em> you'll have to re-engineer the LLVM IR object 
+            model and bitcode writer in your language</li>
+        <li><em>against:</em> it may be harder to track changes to the IR</li>
+      </ul>
+    </li>
+  </ul>
+  <p>If you go with the first option, the C bindings in include/llvm-c should
+     help a lot, since most languages have strong support for interfacing with 
+     C. The most common hurdle with calling C from managed code is interfacing
+     with the garbage collector. The C interface was designed to require very 
+     little memory management, and so is straightforward in this regard.</p>
+</div>
+
 <div class="question"><p><a name="langhlsupp">
   What support is there for a higher level source language constructs for 
   building a compiler?</a></p>
@@ -427,7 +480,7 @@ using <tt>llvm-gcc</tt> instead.</p>
   of running optimizations, linking, and executable generation.</p>
 </div>
 
-<div class="question"><p><a name="langhlsupp">
+<div class="question"><p><a name="getelementptr">
   I don't understand the GetElementPtr instruction. Help!</a></p>
 </div>
 <div class="answer">
@@ -512,7 +565,7 @@ code that you desire.
 
 <div class="question">
 <p>
-<a name="translatec++">Can I use LLVM to convert C++ code to C code?</a>
+<a name="translatecxx">Can I use LLVM to convert C++ code to C code?</a>
 </p>
 </div>