Merge LLVMBuilder and FoldingBuilder, calling

the result IRBuilder.  Patch by Dominic Hamon.


git-svn-id: https://llvm.org/svn/llvm-project/llvm/trunk@49604 91177308-0d34-0410-b5e6-96231b3b80d8

10 files changed, 51 insertions, 62 deletions

diff --git a/docs/tutorial/JITTutorial1.html b/docs/tutorial/JITTutorial1.html
index 4c5a1203c9..4f57a53666 100644
--- a/docs/tutorial/JITTutorial1.html
+++ b/docs/tutorial/JITTutorial1.html
@@ -60,7 +60,7 @@ entry:
 #include <llvm/CallingConv.h>
 #include <llvm/Analysis/Verifier.h>
 #include <llvm/Assembly/PrintModulePass.h>
-#include <llvm/Support/LLVMBuilder.h>
+#include <llvm/Support/IRBuilder.h>
 </pre>
 </div>
 
@@ -143,11 +143,11 @@ Module* makeLLVMModule() {
 <div class="doc_code">
 <pre>
   BasicBlock* block = new BasicBlock("entry", mul_add);
-  LLVMBuilder builder(block);
+  IRBuilder builder(block);
 </pre>
 </div>
 
-<p>We create a new basic block, as you might expect, by calling its constructor.  All we need to tell it is its name and the function to which it belongs.  In addition, we’re creating an <code>LLVMBuilder</code> object, which is a convenience interface for creating instructions and appending them to the end of a block.  Instructions can be created through their constructors as well, but some of their interfaces are quite complicated.  Unless you need a lot of control, using <code>LLVMBuilder</code> will make your life simpler.</p>
+<p>We create a new basic block, as you might expect, by calling its constructor.  All we need to tell it is its name and the function to which it belongs.  In addition, we’re creating an <code>IRBuilder</code> object, which is a convenience interface for creating instructions and appending them to the end of a block.  Instructions can be created through their constructors as well, but some of their interfaces are quite complicated.  Unless you need a lot of control, using <code>IRBuilder</code> will make your life simpler.</p>
 
 <div class="doc_code">
 <pre>
@@ -163,7 +163,7 @@ Module* makeLLVMModule() {
 </pre>
 </div>
 
-<p>The final step in creating our function is to create the instructions that make it up.  Our <code>mul_add</code> function is composed of just three instructions: a multiply, an add, and a return.  <code>LLVMBuilder</code> gives us a simple interface for constructing these instructions and appending them to the “entry” block.  Each of the calls to <code>LLVMBuilder</code> returns a <code>Value*</code> that represents the value yielded by the instruction.  You’ll also notice that, above, <code>x</code>, <code>y</code>, and <code>z</code> are also <code>Value*</code>’s, so it’s clear that instructions operate on <code>Value*</code>’s.</p>
+<p>The final step in creating our function is to create the instructions that make it up.  Our <code>mul_add</code> function is composed of just three instructions: a multiply, an add, and a return.  <code>IRBuilder</code> gives us a simple interface for constructing these instructions and appending them to the “entry” block.  Each of the calls to <code>IRBuilder</code> returns a <code>Value*</code> that represents the value yielded by the instruction.  You’ll also notice that, above, <code>x</code>, <code>y</code>, and <code>z</code> are also <code>Value*</code>’s, so it’s clear that instructions operate on <code>Value*</code>’s.</p>
 
 <p>And that’s it!  Now you can compile and run your code, and get a wonderful textual print out of the LLVM IR we saw at the beginning.  To compile, use the following command line as a guide:</p>
 
diff --git a/docs/tutorial/JITTutorial2.html b/docs/tutorial/JITTutorial2.html
index 70de151fcd..ba3d043ade 100644
--- a/docs/tutorial/JITTutorial2.html
+++ b/docs/tutorial/JITTutorial2.html
@@ -56,7 +56,7 @@ unsigned gcd(unsigned x, unsigned y) {
 #include &lt;llvm/PassManager.h&gt;
 #include &lt;llvm/Analysis/Verifier.h&gt;
 #include &lt;llvm/Assembly/PrintModulePass.h&gt;
-#include &lt;llvm/Support/LLVMBuilder.h&gt;
+#include &lt;llvm/Support/IRBuilder.h&gt;
 
 using namespace llvm;
 
@@ -110,13 +110,13 @@ Module* makeLLVMModule() {
 
 <div class="doc_code">
 <pre>
-  LLVMBuilder builder(entry);
+  IRBuilder builder(entry);
   Value* xEqualsY = builder.CreateICmpEQ(x, y, &quot;tmp&quot;);
   builder.CreateCondBr(xEqualsY, ret, cond_false);
 </pre>
 </div>
 
-<p>Our next block, <code>ret</code>, is pretty simple: it just returns the value of <code>x</code>.  Recall that this block is only reached if <code>x == y</code>, so this is the correct behavior.  Notice that instead of creating a new <code>LLVMBuilder</code> for each block, we can use <code>SetInsertPoint</code> to retarget our existing one.  This saves on construction and memory allocation costs.</p>
+<p>Our next block, <code>ret</code>, is pretty simple: it just returns the value of <code>x</code>.  Recall that this block is only reached if <code>x == y</code>, so this is the correct behavior.  Notice that instead of creating a new <code>IRBuilder</code> for each block, we can use <code>SetInsertPoint</code> to retarget our existing one.  This saves on construction and memory allocation costs.</p>
 
 <div class="doc_code">
 <pre>
diff --git a/docs/tutorial/LangImpl3.html b/docs/tutorial/LangImpl3.html
index 60ad5f1ecd..28b9dac352 100644
--- a/docs/tutorial/LangImpl3.html
+++ b/docs/tutorial/LangImpl3.html
@@ -111,7 +111,7 @@ undeclared parameter):</p>
 Value *ErrorV(const char *Str) { Error(Str); return 0; }
 
 static Module *TheModule;
-static LLVMBuilder Builder;
+static IRBuilder Builder;
 static std::map&lt;std::string, Value*&gt; NamedValues;
 </pre>
 </div>
@@ -123,7 +123,7 @@ uses to contain code.</p>
 
 <p>The <tt>Builder</tt> object is a helper object that makes it easy to generate
 LLVM instructions.  Instances of the <a 
-href="http://llvm.org/doxygen/LLVMBuilder_8h-source.html"><tt>LLVMBuilder</tt></a> 
+href="http://llvm.org/doxygen/IRBuilder_8h-source.html"><tt>IRBuilder</tt></a> 
 class keep track of the current place to insert instructions and has methods to
 create new instructions.</p>
 
@@ -216,7 +216,7 @@ code, we do a simple switch on the opcode to create the right LLVM instruction.
 </p>
 
 <p>In the example above, the LLVM builder class is starting to show its value.  
-LLVMBuilder knows where to insert the newly created instruction, all you have to
+IRBuilder knows where to insert the newly created instruction, all you have to
 do is specify what instruction to create (e.g. with <tt>CreateAdd</tt>), which
 operands to use (<tt>L</tt> and <tt>R</tt> here) and optionally provide a name
 for the generated instruction.</p>
@@ -680,7 +680,7 @@ our makefile/command line about which options to use:</p>
 #include "llvm/DerivedTypes.h"
 #include "llvm/Module.h"
 #include "llvm/Analysis/Verifier.h"
-#include "llvm/Support/LLVMBuilder.h"
+#include "llvm/Support/IRBuilder.h"
 #include &lt;cstdio&gt;
 #include &lt;string&gt;
 #include &lt;map&gt;
@@ -1023,7 +1023,7 @@ static PrototypeAST *ParseExtern() {
 //===----------------------------------------------------------------------===//
 
 static Module *TheModule;
-static LLVMBuilder Builder;
+static IRBuilder Builder;
 static std::map&lt;std::string, Value*&gt; NamedValues;
 
 Value *ErrorV(const char *Str) { Error(Str); return 0; }
diff --git a/docs/tutorial/LangImpl4.html b/docs/tutorial/LangImpl4.html
index 4b9b8c55bd..41b58c76e0 100644
--- a/docs/tutorial/LangImpl4.html
+++ b/docs/tutorial/LangImpl4.html
@@ -56,8 +56,8 @@ Folding</a></div>
 
 <p>
 Our demonstration for Chapter 3 is elegant and easy to extend.  Unfortunately,
-it does not produce wonderful code.  For example, when compiling simple code,
-we don't get obvious optimizations:</p>
+it does not produce wonderful code.  The IRBuilder, however, does give us
+obvious optimizations when compiling simple code:</p>
 
 <div class="doc_code">
 <pre>
@@ -65,36 +65,14 @@ ready&gt; <b>def test(x) 1+2+x;</b>
 Read function definition:
 define double @test(double %x) {
 entry:
-        %addtmp = add double 1.000000e+00, 2.000000e+00
-        %addtmp1 = add double %addtmp, %x
-        ret double %addtmp1
+        %addtmp = add double 3.000000e+00, %x
+        ret double %addtmp
 }
 </pre>
 </div>
 
-<p>This code is a very, very literal transcription of the AST built by parsing
-the input. As such, this transcription lacks optimizations like constant folding (we'd like to get "<tt>add x, 3.0</tt>" in the example above) as well as other more important
-optimizations.  Constant folding, in particular, is a very common and very
-important optimization: so much so that many language implementors implement
-constant folding support in their AST representation.</p>
-
-<p>With LLVM, you don't need this support in the AST.  Since all calls to build LLVM IR go through
-the LLVM builder, it would be nice if the builder itself checked to see if there
-was a constant folding opportunity when you call it.  If so, it could just do
-the constant fold and return the constant instead of creating an instruction.
-This is exactly what the <tt>LLVMFoldingBuilder</tt> class does.  Lets make one
-change:
-
-<div class="doc_code">
-<pre>
-static LLVMFoldingBuilder Builder;
-</pre>
-</div>
-
-<p>All we did was switch from <tt>LLVMBuilder</tt> to 
-<tt>LLVMFoldingBuilder</tt>.  Though we change no other code, we now have all of our
-instructions implicitly constant folded without us having to do anything
-about it.  For example, the input above now compiles to:</p>
+<p>This code is not a literal transcription of the AST built by parsing the 
+input. That would be:
 
 <div class="doc_code">
 <pre>
@@ -102,20 +80,30 @@ ready&gt; <b>def test(x) 1+2+x;</b>
 Read function definition:
 define double @test(double %x) {
 entry:
-        %addtmp = add double 3.000000e+00, %x
-        ret double %addtmp
+        %addtmp = add double 2.000000e+00, 1.000000e+00
+        %addtmp1 = add double %addtmp, %x
+        ret double %addtmp1
 }
 </pre>
 </div>
 
+Constant folding, as seen above, in particular, is a very common and very
+important optimization: so much so that many language implementors implement
+constant folding support in their AST representation.</p>
+
+<p>With LLVM, you don't need this support in the AST.  Since all calls to build 
+LLVM IR go through the LLVM IR builder, the builder itself checked to see if 
+there was a constant folding opportunity when you call it.  If so, it just does 
+the constant fold and return the constant instead of creating an instruction.
+
 <p>Well, that was easy :).  In practice, we recommend always using
-<tt>LLVMFoldingBuilder</tt> when generating code like this.  It has no
+<tt>IRBuilder</tt> when generating code like this.  It has no
 "syntactic overhead" for its use (you don't have to uglify your compiler with
 constant checks everywhere) and it can dramatically reduce the amount of
 LLVM IR that is generated in some cases (particular for languages with a macro
 preprocessor or that use a lot of constants).</p>
 
-<p>On the other hand, the <tt>LLVMFoldingBuilder</tt> is limited by the fact
+<p>On the other hand, the <tt>IRBuilder</tt> is limited by the fact
 that it does all of its analysis inline with the code as it is built.  If you
 take a slightly more complex example:</p>
 
@@ -525,7 +513,7 @@ LLVM JIT and optimizer.  To build this example, use:
 #include "llvm/Analysis/Verifier.h"
 #include "llvm/Target/TargetData.h"
 #include "llvm/Transforms/Scalar.h"
-#include "llvm/Support/LLVMBuilder.h"
+#include "llvm/Support/IRBuilder.h"
 #include &lt;cstdio&gt;
 #include &lt;string&gt;
 #include &lt;map&gt;
@@ -868,7 +856,7 @@ static PrototypeAST *ParseExtern() {
 //===----------------------------------------------------------------------===//
 
 static Module *TheModule;
-static LLVMFoldingBuilder Builder;
+static IRBuilder Builder;
 static std::map&lt;std::string, Value*&gt; NamedValues;
 static FunctionPassManager *TheFPM;
 
diff --git a/docs/tutorial/LangImpl5.html b/docs/tutorial/LangImpl5.html
index f40efb26d8..8081fc3821 100644
--- a/docs/tutorial/LangImpl5.html
+++ b/docs/tutorial/LangImpl5.html
@@ -400,7 +400,7 @@ other two blocks are created, but aren't yet inserted into the function.</p>
 
 <p>Once the blocks are created, we can emit the conditional branch that chooses
 between them.  Note that creating new blocks does not implicitly affect the
-LLVMBuilder, so it is still inserting into the block that the condition
+IRBuilder, so it is still inserting into the block that the condition
 went into.  Also note that it is creating a branch to the "then" block and the
 "else" block, even though the "else" block isn't inserted into the function yet.
 This is all ok: it is the standard way that LLVM supports forward 
@@ -907,7 +907,7 @@ if/then/else and for expressions..  To build this example, use:
 #include "llvm/Analysis/Verifier.h"
 #include "llvm/Target/TargetData.h"
 #include "llvm/Transforms/Scalar.h"
-#include "llvm/Support/LLVMBuilder.h"
+#include "llvm/Support/IRBuilder.h"
 #include &lt;cstdio&gt;
 #include &lt;string&gt;
 #include &lt;map&gt;
@@ -1352,7 +1352,7 @@ static PrototypeAST *ParseExtern() {
 //===----------------------------------------------------------------------===//
 
 static Module *TheModule;
-static LLVMFoldingBuilder Builder;
+static IRBuilder Builder;
 static std::map&lt;std::string, Value*&gt; NamedValues;
 static FunctionPassManager *TheFPM;
 
diff --git a/docs/tutorial/LangImpl6.html b/docs/tutorial/LangImpl6.html
index 62ce43e33f..1f159e0b56 100644
--- a/docs/tutorial/LangImpl6.html
+++ b/docs/tutorial/LangImpl6.html
@@ -827,7 +827,7 @@ if/then/else and for expressions..  To build this example, use:
 #include "llvm/Analysis/Verifier.h"
 #include "llvm/Target/TargetData.h"
 #include "llvm/Transforms/Scalar.h"
-#include "llvm/Support/LLVMBuilder.h"
+#include "llvm/Support/IRBuilder.h"
 #include &lt;cstdio&gt;
 #include &lt;string&gt;
 #include &lt;map&gt;
@@ -1357,7 +1357,7 @@ static PrototypeAST *ParseExtern() {
 //===----------------------------------------------------------------------===//
 
 static Module *TheModule;
-static LLVMFoldingBuilder Builder;
+static IRBuilder Builder;
 static std::map&lt;std::string, Value*&gt; NamedValues;
 static FunctionPassManager *TheFPM;
 
diff --git a/docs/tutorial/LangImpl7.html b/docs/tutorial/LangImpl7.html
index 7138cbdcdf..6d82fa9dbd 100644
--- a/docs/tutorial/LangImpl7.html
+++ b/docs/tutorial/LangImpl7.html
@@ -422,14 +422,14 @@ function:</p>
 /// the function.  This is used for mutable variables etc.
 static AllocaInst *CreateEntryBlockAlloca(Function *TheFunction,
                                           const std::string &amp;VarName) {
-  LLVMBuilder TmpB(&amp;TheFunction-&gt;getEntryBlock(),
-                   TheFunction-&gt;getEntryBlock().begin());
+  IRBuilder TmpB(&amp;TheFunction-&gt;getEntryBlock(),
+                 TheFunction-&gt;getEntryBlock().begin());
   return TmpB.CreateAlloca(Type::DoubleTy, 0, VarName.c_str());
 }
 </pre>
 </div>
 
-<p>This funny looking code creates an LLVMBuilder object that is pointing at
+<p>This funny looking code creates an IRBuilder object that is pointing at
 the first instruction (.begin()) of the entry block.  It then creates an alloca
 with the expected name and returns it.  Because all values in Kaleidoscope are
 doubles, there is no need to pass in a type to use.</p>
@@ -1009,7 +1009,7 @@ variables and var/in support.  To build this example, use:
 #include "llvm/Analysis/Verifier.h"
 #include "llvm/Target/TargetData.h"
 #include "llvm/Transforms/Scalar.h"
-#include "llvm/Support/LLVMBuilder.h"
+#include "llvm/Support/IRBuilder.h"
 #include &lt;cstdio&gt;
 #include &lt;string&gt;
 #include &lt;map&gt;
@@ -1605,7 +1605,7 @@ static PrototypeAST *ParseExtern() {
 //===----------------------------------------------------------------------===//
 
 static Module *TheModule;
-static LLVMFoldingBuilder Builder;
+static IRBuilder Builder;
 static std::map&lt;std::string, AllocaInst*&gt; NamedValues;
 static FunctionPassManager *TheFPM;
 
@@ -1615,8 +1615,8 @@ Value *ErrorV(const char *Str) { Error(Str); return 0; }
 /// the function.  This is used for mutable variables etc.
 static AllocaInst *CreateEntryBlockAlloca(Function *TheFunction,
                                           const std::string &amp;VarName) {
-  LLVMBuilder TmpB(&amp;TheFunction-&gt;getEntryBlock(),
-                   TheFunction-&gt;getEntryBlock().begin());
+  IRBuilder TmpB(&amp;TheFunction-&gt;getEntryBlock(),
+                 TheFunction-&gt;getEntryBlock().begin());
   return TmpB.CreateAlloca(Type::DoubleTy, 0, VarName.c_str());
 }
 
diff --git a/docs/tutorial/OCamlLangImpl3.html b/docs/tutorial/OCamlLangImpl3.html
index 079ab1c2b4..b396ef07ae 100644
--- a/docs/tutorial/OCamlLangImpl3.html
+++ b/docs/tutorial/OCamlLangImpl3.html
@@ -108,7 +108,7 @@ top-level structure that the LLVM IR uses to contain code.</p>
 
 <p>The <tt>Codegen.builder</tt> object is a helper object that makes it easy to
 generate LLVM instructions.  Instances of the <a
-href="http://llvm.org/doxygen/LLVMBuilder_8h-source.html"><tt>LLVMBuilder</tt></a>
+href="http://llvm.org/doxygen/IRBuilder_8h-source.html"><tt>IRBuilder</tt></a>
 class keep track of the current place to insert instructions and has methods to
 create new instructions.</p>
 
@@ -194,7 +194,7 @@ code, we do a simple switch on the opcode to create the right LLVM instruction.
 </p>
 
 <p>In the example above, the LLVM builder class is starting to show its value.
-LLVMBuilder knows where to insert the newly created instruction, all you have to
+IRBuilder knows where to insert the newly created instruction, all you have to
 do is specify what instruction to create (e.g. with <tt>Llvm.create_add</tt>),
 which operands to use (<tt>lhs</tt> and <tt>rhs</tt> here) and optionally
 provide a name for the generated instruction.</p>
diff --git a/docs/tutorial/OCamlLangImpl4.html b/docs/tutorial/OCamlLangImpl4.html
index 4e267b80f5..ffa85d51df 100644
--- a/docs/tutorial/OCamlLangImpl4.html
+++ b/docs/tutorial/OCamlLangImpl4.html
@@ -58,7 +58,8 @@ Folding</a></div>
 
 <div class="doc_text">
 
-<p><b>Note:</b> the ocaml bindings already use <tt>LLVMFoldingBuilder</tt>.<p>
+<p><b>Note:</b> the default <tt>IRBuilder</tt> now always includes the constant 
+folding optimisations below.<p>
 
 <p>
 Our demonstration for Chapter 3 is elegant and easy to extend.  Unfortunately,
diff --git a/docs/tutorial/OCamlLangImpl5.html b/docs/tutorial/OCamlLangImpl5.html
index ba8c2f791d..594a77d164 100644
--- a/docs/tutorial/OCamlLangImpl5.html
+++ b/docs/tutorial/OCamlLangImpl5.html
@@ -455,7 +455,7 @@ to create the PHI node and set up the block/value pairs for the PHI.</p>
 
 <p>Once the blocks are created, we can emit the conditional branch that chooses
 between them.  Note that creating new blocks does not implicitly affect the
-LLVMBuilder, so it is still inserting into the block that the condition
+IRBuilder, so it is still inserting into the block that the condition
 went into.  This is why we needed to save the "start" block.</p>
 
 <div class="doc_code">