docs/tutorial/OCamlLangImpl5.html

   1 <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN"
   2                       "http://www.w3.org/TR/html4/strict.dtd">
   3
   4 <html>
   5 <head>
   6   <title>Kaleidoscope: Extending the Language: Control Flow</title>
   7   <meta http-equiv="Content-Type" content="text/html; charset=utf-8">
   8   <meta name="author" content="Chris Lattner">
   9   <meta name="author" content="Erick Tryzelaar">
  10   <link rel="stylesheet" href="../llvm.css" type="text/css">
  11 </head>
  12
  13 <body>
  14
  15 <div class="doc_title">Kaleidoscope: Extending the Language: Control Flow</div>
  16
  17 <ul>
  18 <li><a href="index.html">Up to Tutorial Index</a></li>
  19 <li>Chapter 5
  20   <ol>
  21     <li><a href="#intro">Chapter 5 Introduction</a></li>
  22     <li><a href="#ifthen">If/Then/Else</a>
  23     <ol>
  24       <li><a href="#iflexer">Lexer Extensions</a></li>
  25       <li><a href="#ifast">AST Extensions</a></li>
  26       <li><a href="#ifparser">Parser Extensions</a></li>
  27       <li><a href="#ifir">LLVM IR</a></li>
  28       <li><a href="#ifcodegen">Code Generation</a></li>
  29     </ol>
  30     </li>
  31     <li><a href="#for">'for' Loop Expression</a>
  32     <ol>
  33       <li><a href="#forlexer">Lexer Extensions</a></li>
  34       <li><a href="#forast">AST Extensions</a></li>
  35       <li><a href="#forparser">Parser Extensions</a></li>
  36       <li><a href="#forir">LLVM IR</a></li>
  37       <li><a href="#forcodegen">Code Generation</a></li>
  38     </ol>
  39     </li>
  40     <li><a href="#code">Full Code Listing</a></li>
  41   </ol>
  42 </li>
  43 <li><a href="OCamlLangImpl6.html">Chapter 6</a>: Extending the Language:
  44 User-defined Operators</li>
  45 </ul>
  46
  47 <div class="doc_author">
  48         <p>
  49                 Written by <a href="mailto:sabre@nondot.org">Chris Lattner</a>
  50                 and <a href="mailto:idadesub@users.sourceforge.net">Erick Tryzelaar</a>
  51         </p>
  52 </div>
  53
  54 <!-- *********************************************************************** -->
  55 <div class="doc_section"><a name="intro">Chapter 5 Introduction</a></div>
  56 <!-- *********************************************************************** -->
  57
  58 <div class="doc_text">
  59
  60 <p>Welcome to Chapter 5 of the "<a href="index.html">Implementing a language
  61 with LLVM</a>" tutorial.  Parts 1-4 described the implementation of the simple
  62 Kaleidoscope language and included support for generating LLVM IR, followed by
  63 optimizations and a JIT compiler.  Unfortunately, as presented, Kaleidoscope is
  64 mostly useless: it has no control flow other than call and return.  This means
  65 that you can't have conditional branches in the code, significantly limiting its
  66 power.  In this episode of "build that compiler", we'll extend Kaleidoscope to
  67 have an if/then/else expression plus a simple 'for' loop.</p>
  68
  69 </div>
  70
  71 <!-- *********************************************************************** -->
  72 <div class="doc_section"><a name="ifthen">If/Then/Else</a></div>
  73 <!-- *********************************************************************** -->
  74
  75 <div class="doc_text">
  76
  77 <p>
  78 Extending Kaleidoscope to support if/then/else is quite straightforward.  It
  79 basically requires adding lexer support for this "new" concept to the lexer,
  80 parser, AST, and LLVM code emitter.  This example is nice, because it shows how
  81 easy it is to "grow" a language over time, incrementally extending it as new
  82 ideas are discovered.</p>
  83
  84 <p>Before we get going on "how" we add this extension, lets talk about "what" we
  85 want.  The basic idea is that we want to be able to write this sort of thing:
  86 </p>
  87
  88 <div class="doc_code">
  89 <pre>
  90 def fib(x)
  91   if x &lt; 3 then
  92     1
  93   else
  94     fib(x-1)+fib(x-2);
  95 </pre>
  96 </div>
  97
  98 <p>In Kaleidoscope, every construct is an expression: there are no statements.
  99 As such, the if/then/else expression needs to return a value like any other.
 100 Since we're using a mostly functional form, we'll have it evaluate its
 101 conditional, then return the 'then' or 'else' value based on how the condition
 102 was resolved.  This is very similar to the C "?:" expression.</p>
 103
 104 <p>The semantics of the if/then/else expression is that it evaluates the
 105 condition to a boolean equality value: 0.0 is considered to be false and
 106 everything else is considered to be true.
 107 If the condition is true, the first subexpression is evaluated and returned, if
 108 the condition is false, the second subexpression is evaluated and returned.
 109 Since Kaleidoscope allows side-effects, this behavior is important to nail down.
 110 </p>
 111
 112 <p>Now that we know what we "want", lets break this down into its constituent
 113 pieces.</p>
 114
 115 </div>
 116
 117 <!-- ======================================================================= -->
 118 <div class="doc_subsubsection"><a name="iflexer">Lexer Extensions for
 119 If/Then/Else</a></div>
 120 <!-- ======================================================================= -->
 121
 122
 123 <div class="doc_text">
 124
 125 <p>The lexer extensions are straightforward.  First we add new variants
 126 for the relevant tokens:</p>
 127
 128 <div class="doc_code">
 129 <pre>
 130   (* control *)
 131   | If | Then | Else | For | In
 132 </pre>
 133 </div>
 134
 135 <p>Once we have that, we recognize the new keywords in the lexer. This is pretty simple
 136 stuff:</p>
 137
 138 <div class="doc_code">
 139 <pre>
 140       ...
 141       match Buffer.contents buffer with
 142       | "def" -&gt; [&lt; 'Token.Def; stream &gt;]
 143       | "extern" -&gt; [&lt; 'Token.Extern; stream &gt;]
 144       | "if" -&gt; [&lt; 'Token.If; stream &gt;]
 145       | "then" -&gt; [&lt; 'Token.Then; stream &gt;]
 146       | "else" -&gt; [&lt; 'Token.Else; stream &gt;]
 147       | "for" -&gt; [&lt; 'Token.For; stream &gt;]
 148       | "in" -&gt; [&lt; 'Token.In; stream &gt;]
 149       | id -&gt; [&lt; 'Token.Ident id; stream &gt;]
 150 </pre>
 151 </div>
 152
 153 </div>
 154
 155 <!-- ======================================================================= -->
 156 <div class="doc_subsubsection"><a name="ifast">AST Extensions for
 157  If/Then/Else</a></div>
 158 <!-- ======================================================================= -->
 159
 160 <div class="doc_text">
 161
 162 <p>To represent the new expression we add a new AST variant for it:</p>
 163
 164 <div class="doc_code">
 165 <pre>
 166 type expr =
 167   ...
 168   (* variant for if/then/else. *)
 169   | If of expr * expr * expr
 170 </pre>
 171 </div>
 172
 173 <p>The AST variant just has pointers to the various subexpressions.</p>
 174
 175 </div>
 176
 177 <!-- ======================================================================= -->
 178 <div class="doc_subsubsection"><a name="ifparser">Parser Extensions for
 179 If/Then/Else</a></div>
 180 <!-- ======================================================================= -->
 181
 182 <div class="doc_text">
 183
 184 <p>Now that we have the relevant tokens coming from the lexer and we have the
 185 AST node to build, our parsing logic is relatively straightforward.  First we
 186 define a new parsing function:</p>
 187
 188 <div class="doc_code">
 189 <pre>
 190 let rec parse_primary = parser
 191   ...
 192   (* ifexpr ::= 'if' expr 'then' expr 'else' expr *)
 193   | [&lt; 'Token.If; c=parse_expr;
 194        'Token.Then ?? "expected 'then'"; t=parse_expr;
 195        'Token.Else ?? "expected 'else'"; e=parse_expr &gt;] -&gt;
 196       Ast.If (c, t, e)
 197 </pre>
 198 </div>
 199
 200 <p>Next we hook it up as a primary expression:</p>
 201
 202 <div class="doc_code">
 203 <pre>
 204 let rec parse_primary = parser
 205   ...
 206   (* ifexpr ::= 'if' expr 'then' expr 'else' expr *)
 207   | [&lt; 'Token.If; c=parse_expr;
 208        'Token.Then ?? "expected 'then'"; t=parse_expr;
 209        'Token.Else ?? "expected 'else'"; e=parse_expr &gt;] -&gt;
 210       Ast.If (c, t, e)
 211 </pre>
 212 </div>
 213
 214 </div>
 215
 216 <!-- ======================================================================= -->
 217 <div class="doc_subsubsection"><a name="ifir">LLVM IR for If/Then/Else</a></div>
 218 <!-- ======================================================================= -->
 219
 220 <div class="doc_text">
 221
 222 <p>Now that we have it parsing and building the AST, the final piece is adding
 223 LLVM code generation support.  This is the most interesting part of the
 224 if/then/else example, because this is where it starts to introduce new concepts.
 225 All of the code above has been thoroughly described in previous chapters.
 226 </p>
 227
 228 <p>To motivate the code we want to produce, lets take a look at a simple
 229 example.  Consider:</p>
 230
 231 <div class="doc_code">
 232 <pre>
 233 extern foo();
 234 extern bar();
 235 def baz(x) if x then foo() else bar();
 236 </pre>
 237 </div>
 238
 239 <p>If you disable optimizations, the code you'll (soon) get from Kaleidoscope
 240 looks like this:</p>
 241
 242 <div class="doc_code">
 243 <pre>
 244 declare double @foo()
 245
 246 declare double @bar()
 247
 248 define double @baz(double %x) {
 249 entry:
 250   %ifcond = fcmp one double %x, 0.000000e+00
 251   br i1 %ifcond, label %then, label %else
 252
 253 then:    ; preds = %entry
 254   %calltmp = call double @foo()
 255   br label %ifcont
 256
 257 else:    ; preds = %entry
 258   %calltmp1 = call double @bar()
 259   br label %ifcont
 260
 261 ifcont:    ; preds = %else, %then
 262   %iftmp = phi double [ %calltmp, %then ], [ %calltmp1, %else ]
 263   ret double %iftmp
 264 }
 265 </pre>
 266 </div>
 267
 268 <p>To visualize the control flow graph, you can use a nifty feature of the LLVM
 269 '<a href="http://llvm.org/cmds/opt.html">opt</a>' tool.  If you put this LLVM IR
 270 into "t.ll" and run "<tt>llvm-as &lt; t.ll | opt -analyze -view-cfg</tt>", <a
 271 href="../ProgrammersManual.html#ViewGraph">a window will pop up</a> and you'll
 272 see this graph:</p>
 273
 274 <div style="text-align: center"><img src="LangImpl5-cfg.png" alt="Example CFG" width="423"
 275 height="315"></div>
 276
 277 <p>Another way to get this is to call "<tt>Llvm_analysis.view_function_cfg
 278 f</tt>" or "<tt>Llvm_analysis.view_function_cfg_only f</tt>" (where <tt>f</tt>
 279 is a "<tt>Function</tt>") either by inserting actual calls into the code and
 280 recompiling or by calling these in the debugger.  LLVM has many nice features
 281 for visualizing various graphs.</p>
 282
 283 <p>Getting back to the generated code, it is fairly simple: the entry block
 284 evaluates the conditional expression ("x" in our case here) and compares the
 285 result to 0.0 with the "<tt><a href="../LangRef.html#i_fcmp">fcmp</a> one</tt>"
 286 instruction ('one' is "Ordered and Not Equal").  Based on the result of this
 287 expression, the code jumps to either the "then" or "else" blocks, which contain
 288 the expressions for the true/false cases.</p>
 289
 290 <p>Once the then/else blocks are finished executing, they both branch back to the
 291 'ifcont' block to execute the code that happens after the if/then/else.  In this
 292 case the only thing left to do is to return to the caller of the function.  The
 293 question then becomes: how does the code know which expression to return?</p>
 294
 295 <p>The answer to this question involves an important SSA operation: the
 296 <a href="http://en.wikipedia.org/wiki/Static_single_assignment_form">Phi
 297 operation</a>.  If you're not familiar with SSA, <a
 298 href="http://en.wikipedia.org/wiki/Static_single_assignment_form">the wikipedia
 299 article</a> is a good introduction and there are various other introductions to
 300 it available on your favorite search engine.  The short version is that
 301 "execution" of the Phi operation requires "remembering" which block control came
 302 from.  The Phi operation takes on the value corresponding to the input control
 303 block.  In this case, if control comes in from the "then" block, it gets the
 304 value of "calltmp".  If control comes from the "else" block, it gets the value
 305 of "calltmp1".</p>
 306
 307 <p>At this point, you are probably starting to think "Oh no! This means my
 308 simple and elegant front-end will have to start generating SSA form in order to
 309 use LLVM!".  Fortunately, this is not the case, and we strongly advise
 310 <em>not</em> implementing an SSA construction algorithm in your front-end
 311 unless there is an amazingly good reason to do so.  In practice, there are two
 312 sorts of values that float around in code written for your average imperative
 313 programming language that might need Phi nodes:</p>
 314
 315 <ol>
 316 <li>Code that involves user variables: <tt>x = 1; x = x + 1; </tt></li>
 317 <li>Values that are implicit in the structure of your AST, such as the Phi node
 318 in this case.</li>
 319 </ol>
 320
 321 <p>In <a href="OCamlLangImpl7.html">Chapter 7</a> of this tutorial ("mutable
 322 variables"), we'll talk about #1
 323 in depth.  For now, just believe me that you don't need SSA construction to
 324 handle this case.  For #2, you have the choice of using the techniques that we will
 325 describe for #1, or you can insert Phi nodes directly, if convenient.  In this
 326 case, it is really really easy to generate the Phi node, so we choose to do it
 327 directly.</p>
 328
 329 <p>Okay, enough of the motivation and overview, lets generate code!</p>
 330
 331 </div>
 332
 333 <!-- ======================================================================= -->
 334 <div class="doc_subsubsection"><a name="ifcodegen">Code Generation for
 335 If/Then/Else</a></div>
 336 <!-- ======================================================================= -->
 337
 338 <div class="doc_text">
 339
 340 <p>In order to generate code for this, we implement the <tt>Codegen</tt> method
 341 for <tt>IfExprAST</tt>:</p>
 342
 343 <div class="doc_code">
 344 <pre>
 345 let rec codegen_expr = function
 346   ...
 347   | Ast.If (cond, then_, else_) -&gt;
 348       let cond = codegen_expr cond in
 349
 350       (* Convert condition to a bool by comparing equal to 0.0 *)
 351       let zero = const_float double_type 0.0 in
 352       let cond_val = build_fcmp Fcmp.One cond zero "ifcond" builder in
 353 </pre>
 354 </div>
 355
 356 <p>This code is straightforward and similar to what we saw before.  We emit the
 357 expression for the condition, then compare that value to zero to get a truth
 358 value as a 1-bit (bool) value.</p>
 359
 360 <div class="doc_code">
 361 <pre>
 362       (* Grab the first block so that we might later add the conditional branch
 363        * to it at the end of the function. *)
 364       let start_bb = insertion_block builder in
 365       let the_function = block_parent start_bb in
 366
 367       let then_bb = append_block "then" the_function in
 368       position_at_end then_bb builder;
 369 </pre>
 370 </div>
 371
 372 <p>
 373 As opposed to the <a href="LangImpl5.html">C++ tutorial</a>, we have to build
 374 our basic blocks bottom up since we can't have dangling BasicBlocks.  We start
 375 off by saving a pointer to the first block (which might not be the entry
 376 block), which we'll need to build a conditional branch later.  We do this by
 377 asking the <tt>builder</tt> for the current BasicBlock.  The fourth line
 378 gets the current Function object that is being built.  It gets this by the
 379 <tt>start_bb</tt> for its "parent" (the function it is currently embedded
 380 into).</p>
 381
 382 <p>Once it has that, it creates one block.  It is automatically appended into
 383 the function's list of blocks.</p>
 384
 385 <div class="doc_code">
 386 <pre>
 387       (* Emit 'then' value. *)
 388       position_at_end then_bb builder;
 389       let then_val = codegen_expr then_ in
 390
 391       (* Codegen of 'then' can change the current block, update then_bb for the
 392        * phi. We create a new name because one is used for the phi node, and the
 393        * other is used for the conditional branch. *)
 394       let new_then_bb = insertion_block builder in
 395 </pre>
 396 </div>
 397
 398 <p>We move the builder to start inserting into the "then" block.  Strictly
 399 speaking, this call moves the insertion point to be at the end of the specified
 400 block.  However, since the "then" block is empty, it also starts out by
 401 inserting at the beginning of the block.  :)</p>
 402
 403 <p>Once the insertion point is set, we recursively codegen the "then" expression
 404 from the AST.</p>
 405
 406 <p>The final line here is quite subtle, but is very important.  The basic issue
 407 is that when we create the Phi node in the merge block, we need to set up the
 408 block/value pairs that indicate how the Phi will work.  Importantly, the Phi
 409 node expects to have an entry for each predecessor of the block in the CFG.  Why
 410 then, are we getting the current block when we just set it to ThenBB 5 lines
 411 above?  The problem is that the "Then" expression may actually itself change the
 412 block that the Builder is emitting into if, for example, it contains a nested
 413 "if/then/else" expression.  Because calling Codegen recursively could
 414 arbitrarily change the notion of the current block, we are required to get an
 415 up-to-date value for code that will set up the Phi node.</p>
 416
 417 <div class="doc_code">
 418 <pre>
 419       (* Emit 'else' value. *)
 420       let else_bb = append_block "else" the_function in
 421       position_at_end else_bb builder;
 422       let else_val = codegen_expr else_ in
 423
 424       (* Codegen of 'else' can change the current block, update else_bb for the
 425        * phi. *)
 426       let new_else_bb = insertion_block builder in
 427 </pre>
 428 </div>
 429
 430 <p>Code generation for the 'else' block is basically identical to codegen for
 431 the 'then' block.</p>
 432
 433 <div class="doc_code">
 434 <pre>
 435       (* Emit merge block. *)
 436       let merge_bb = append_block "ifcont" the_function in
 437       position_at_end merge_bb builder;
 438       let incoming = [(then_val, new_then_bb); (else_val, new_else_bb)] in
 439       let phi = build_phi incoming "iftmp" builder in
 440 </pre>
 441 </div>
 442
 443 <p>The first two lines here are now familiar: the first adds the "merge" block
 444 to the Function object.  The second block changes the insertion point so that
 445 newly created code will go into the "merge" block.  Once that is done, we need
 446 to create the PHI node and set up the block/value pairs for the PHI.</p>
 447
 448 <div class="doc_code">
 449 <pre>
 450       (* Return to the start block to add the conditional branch. *)
 451       position_at_end start_bb builder;
 452       ignore (build_cond_br cond_val then_bb else_bb builder);
 453 </pre>
 454 </div>
 455
 456 <p>Once the blocks are created, we can emit the conditional branch that chooses
 457 between them.  Note that creating new blocks does not implicitly affect the
 458 IRBuilder, so it is still inserting into the block that the condition
 459 went into.  This is why we needed to save the "start" block.</p>
 460
 461 <div class="doc_code">
 462 <pre>
 463       (* Set a unconditional branch at the end of the 'then' block and the
 464        * 'else' block to the 'merge' block. *)
 465       position_at_end new_then_bb builder; ignore (build_br merge_bb builder);
 466       position_at_end new_else_bb builder; ignore (build_br merge_bb builder);
 467
 468       (* Finally, set the builder to the end of the merge block. *)
 469       position_at_end merge_bb builder;
 470
 471       phi
 472 </pre>
 473 </div>
 474
 475 <p>To finish off the blocks, we create an unconditional branch
 476 to the merge block.  One interesting (and very important) aspect of the LLVM IR
 477 is that it <a href="../LangRef.html#functionstructure">requires all basic blocks
 478 to be "terminated"</a> with a <a href="../LangRef.html#terminators">control flow
 479 instruction</a> such as return or branch.  This means that all control flow,
 480 <em>including fall throughs</em> must be made explicit in the LLVM IR.  If you
 481 violate this rule, the verifier will emit an error.
 482
 483 <p>Finally, the CodeGen function returns the phi node as the value computed by
 484 the if/then/else expression.  In our example above, this returned value will
 485 feed into the code for the top-level function, which will create the return
 486 instruction.</p>
 487
 488 <p>Overall, we now have the ability to execute conditional code in
 489 Kaleidoscope.  With this extension, Kaleidoscope is a fairly complete language
 490 that can calculate a wide variety of numeric functions.  Next up we'll add
 491 another useful expression that is familiar from non-functional languages...</p>
 492
 493 </div>
 494
 495 <!-- *********************************************************************** -->
 496 <div class="doc_section"><a name="for">'for' Loop Expression</a></div>
 497 <!-- *********************************************************************** -->
 498
 499 <div class="doc_text">
 500
 501 <p>Now that we know how to add basic control flow constructs to the language,
 502 we have the tools to add more powerful things.  Lets add something more
 503 aggressive, a 'for' expression:</p>
 504
 505 <div class="doc_code">
 506 <pre>
 507  extern putchard(char);
 508  def printstar(n)
 509    for i = 1, i &lt; n, 1.0 in
 510      putchard(42);  # ascii 42 = '*'
 511
 512  # print 100 '*' characters
 513  printstar(100);
 514 </pre>
 515 </div>
 516
 517 <p>This expression defines a new variable ("i" in this case) which iterates from
 518 a starting value, while the condition ("i &lt; n" in this case) is true,
 519 incrementing by an optional step value ("1.0" in this case).  If the step value
 520 is omitted, it defaults to 1.0.  While the loop is true, it executes its
 521 body expression.  Because we don't have anything better to return, we'll just
 522 define the loop as always returning 0.0.  In the future when we have mutable
 523 variables, it will get more useful.</p>
 524
 525 <p>As before, lets talk about the changes that we need to Kaleidoscope to
 526 support this.</p>
 527
 528 </div>
 529
 530 <!-- ======================================================================= -->
 531 <div class="doc_subsubsection"><a name="forlexer">Lexer Extensions for
 532 the 'for' Loop</a></div>
 533 <!-- ======================================================================= -->
 534
 535 <div class="doc_text">
 536
 537 <p>The lexer extensions are the same sort of thing as for if/then/else:</p>
 538
 539 <div class="doc_code">
 540 <pre>
 541   ... in Token.token ...
 542   (* control *)
 543   | If | Then | Else
 544   <b>| For | In</b>
 545
 546   ... in Lexer.lex_ident...
 547       match Buffer.contents buffer with
 548       | "def" -&gt; [&lt; 'Token.Def; stream &gt;]
 549       | "extern" -&gt; [&lt; 'Token.Extern; stream &gt;]
 550       | "if" -&gt; [&lt; 'Token.If; stream &gt;]
 551       | "then" -&gt; [&lt; 'Token.Then; stream &gt;]
 552       | "else" -&gt; [&lt; 'Token.Else; stream &gt;]
 553       <b>| "for" -&gt; [&lt; 'Token.For; stream &gt;]
 554       | "in" -&gt; [&lt; 'Token.In; stream &gt;]</b>
 555       | id -&gt; [&lt; 'Token.Ident id; stream &gt;]
 556 </pre>
 557 </div>
 558
 559 </div>
 560
 561 <!-- ======================================================================= -->
 562 <div class="doc_subsubsection"><a name="forast">AST Extensions for
 563 the 'for' Loop</a></div>
 564 <!-- ======================================================================= -->
 565
 566 <div class="doc_text">
 567
 568 <p>The AST variant is just as simple.  It basically boils down to capturing
 569 the variable name and the constituent expressions in the node.</p>
 570
 571 <div class="doc_code">
 572 <pre>
 573 type expr =
 574   ...
 575   (* variant for for/in. *)
 576   | For of string * expr * expr * expr option * expr
 577 </pre>
 578 </div>
 579
 580 </div>
 581
 582 <!-- ======================================================================= -->
 583 <div class="doc_subsubsection"><a name="forparser">Parser Extensions for
 584 the 'for' Loop</a></div>
 585 <!-- ======================================================================= -->
 586
 587 <div class="doc_text">
 588
 589 <p>The parser code is also fairly standard.  The only interesting thing here is
 590 handling of the optional step value.  The parser code handles it by checking to
 591 see if the second comma is present.  If not, it sets the step value to null in
 592 the AST node:</p>
 593
 594 <div class="doc_code">
 595 <pre>
 596 let rec parse_primary = parser
 597   ...
 598   (* forexpr
 599         ::= 'for' identifier '=' expr ',' expr (',' expr)? 'in' expression *)
 600   | [&lt; 'Token.For;
 601        'Token.Ident id ?? "expected identifier after for";
 602        'Token.Kwd '=' ?? "expected '=' after for";
 603        stream &gt;] -&gt;
 604       begin parser
 605         | [&lt;
 606              start=parse_expr;
 607              'Token.Kwd ',' ?? "expected ',' after for";
 608              end_=parse_expr;
 609              stream &gt;] -&gt;
 610             let step =
 611               begin parser
 612               | [&lt; 'Token.Kwd ','; step=parse_expr &gt;] -&gt; Some step
 613               | [&lt; &gt;] -&gt; None
 614               end stream
 615             in
 616             begin parser
 617             | [&lt; 'Token.In; body=parse_expr &gt;] -&gt;
 618                 Ast.For (id, start, end_, step, body)
 619             | [&lt; &gt;] -&gt;
 620                 raise (Stream.Error "expected 'in' after for")
 621             end stream
 622         | [&lt; &gt;] -&gt;
 623             raise (Stream.Error "expected '=' after for")
 624       end stream
 625 </pre>
 626 </div>
 627
 628 </div>
 629
 630 <!-- ======================================================================= -->
 631 <div class="doc_subsubsection"><a name="forir">LLVM IR for
 632 the 'for' Loop</a></div>
 633 <!-- ======================================================================= -->
 634
 635 <div class="doc_text">
 636
 637 <p>Now we get to the good part: the LLVM IR we want to generate for this thing.
 638 With the simple example above, we get this LLVM IR (note that this dump is
 639 generated with optimizations disabled for clarity):
 640 </p>
 641
 642 <div class="doc_code">
 643 <pre>
 644 declare double @putchard(double)
 645
 646 define double @printstar(double %n) {
 647 entry:
 648         ; initial value = 1.0 (inlined into phi)
 649   br label %loop
 650
 651 loop:    ; preds = %loop, %entry
 652   %i = phi double [ 1.000000e+00, %entry ], [ %nextvar, %loop ]
 653         ; body
 654   %calltmp = call double @putchard( double 4.200000e+01 )
 655         ; increment
 656   %nextvar = add double %i, 1.000000e+00
 657
 658         ; termination test
 659   %cmptmp = fcmp ult double %i, %n
 660   %booltmp = uitofp i1 %cmptmp to double
 661   %loopcond = fcmp one double %booltmp, 0.000000e+00
 662   br i1 %loopcond, label %loop, label %afterloop
 663
 664 afterloop:    ; preds = %loop
 665         ; loop always returns 0.0
 666   ret double 0.000000e+00
 667 }
 668 </pre>
 669 </div>
 670
 671 <p>This loop contains all the same constructs we saw before: a phi node, several
 672 expressions, and some basic blocks.  Lets see how this fits together.</p>
 673
 674 </div>
 675
 676 <!-- ======================================================================= -->
 677 <div class="doc_subsubsection"><a name="forcodegen">Code Generation for
 678 the 'for' Loop</a></div>
 679 <!-- ======================================================================= -->
 680
 681 <div class="doc_text">
 682
 683 <p>The first part of Codegen is very simple: we just output the start expression
 684 for the loop value:</p>
 685
 686 <div class="doc_code">
 687 <pre>
 688 let rec codegen_expr = function
 689   ...
 690   | Ast.For (var_name, start, end_, step, body) -&gt;
 691       (* Emit the start code first, without 'variable' in scope. *)
 692       let start_val = codegen_expr start in
 693 </pre>
 694 </div>
 695
 696 <p>With this out of the way, the next step is to set up the LLVM basic block
 697 for the start of the loop body.  In the case above, the whole loop body is one
 698 block, but remember that the body code itself could consist of multiple blocks
 699 (e.g. if it contains an if/then/else or a for/in expression).</p>
 700
 701 <div class="doc_code">
 702 <pre>
 703       (* Make the new basic block for the loop header, inserting after current
 704        * block. *)
 705       let preheader_bb = insertion_block builder in
 706       let the_function = block_parent preheader_bb in
 707       let loop_bb = append_block "loop" the_function in
 708
 709       (* Insert an explicit fall through from the current block to the
 710        * loop_bb. *)
 711       ignore (build_br loop_bb builder);
 712 </pre>
 713 </div>
 714
 715 <p>This code is similar to what we saw for if/then/else.  Because we will need
 716 it to create the Phi node, we remember the block that falls through into the
 717 loop.  Once we have that, we create the actual block that starts the loop and
 718 create an unconditional branch for the fall-through between the two blocks.</p>
 719
 720 <div class="doc_code">
 721 <pre>
 722       (* Start insertion in loop_bb. *)
 723       position_at_end loop_bb builder;
 724
 725       (* Start the PHI node with an entry for start. *)
 726       let variable = build_phi [(start_val, preheader_bb)] var_name builder in
 727 </pre>
 728 </div>
 729
 730 <p>Now that the "preheader" for the loop is set up, we switch to emitting code
 731 for the loop body.  To begin with, we move the insertion point and create the
 732 PHI node for the loop induction variable.  Since we already know the incoming
 733 value for the starting value, we add it to the Phi node.  Note that the Phi will
 734 eventually get a second value for the backedge, but we can't set it up yet
 735 (because it doesn't exist!).</p>
 736
 737 <div class="doc_code">
 738 <pre>
 739       (* Within the loop, the variable is defined equal to the PHI node. If it
 740        * shadows an existing variable, we have to restore it, so save it
 741        * now. *)
 742       let old_val =
 743         try Some (Hashtbl.find named_values var_name) with Not_found -&gt; None
 744       in
 745       Hashtbl.add named_values var_name variable;
 746
 747       (* Emit the body of the loop.  This, like any other expr, can change the
 748        * current BB.  Note that we ignore the value computed by the body, but
 749        * don't allow an error *)
 750       ignore (codegen_expr body);
 751 </pre>
 752 </div>
 753
 754 <p>Now the code starts to get more interesting.  Our 'for' loop introduces a new
 755 variable to the symbol table.  This means that our symbol table can now contain
 756 either function arguments or loop variables.  To handle this, before we codegen
 757 the body of the loop, we add the loop variable as the current value for its
 758 name.  Note that it is possible that there is a variable of the same name in the
 759 outer scope.  It would be easy to make this an error (emit an error and return
 760 null if there is already an entry for VarName) but we choose to allow shadowing
 761 of variables.  In order to handle this correctly, we remember the Value that
 762 we are potentially shadowing in <tt>old_val</tt> (which will be None if there is
 763 no shadowed variable).</p>
 764
 765 <p>Once the loop variable is set into the symbol table, the code recursively
 766 codegen's the body.  This allows the body to use the loop variable: any
 767 references to it will naturally find it in the symbol table.</p>
 768
 769 <div class="doc_code">
 770 <pre>
 771       (* Emit the step value. *)
 772       let step_val =
 773         match step with
 774         | Some step -&gt; codegen_expr step
 775         (* If not specified, use 1.0. *)
 776         | None -&gt; const_float double_type 1.0
 777       in
 778
 779       let next_var = build_add variable step_val "nextvar" builder in
 780 </pre>
 781 </div>
 782
 783 <p>Now that the body is emitted, we compute the next value of the iteration
 784 variable by adding the step value, or 1.0 if it isn't present.
 785 '<tt>next_var</tt>' will be the value of the loop variable on the next iteration
 786 of the loop.</p>
 787
 788 <div class="doc_code">
 789 <pre>
 790       (* Compute the end condition. *)
 791       let end_cond = codegen_expr end_ in
 792
 793       (* Convert condition to a bool by comparing equal to 0.0. *)
 794       let zero = const_float double_type 0.0 in
 795       let end_cond = build_fcmp Fcmp.One end_cond zero "loopcond" builder in
 796 </pre>
 797 </div>
 798
 799 <p>Finally, we evaluate the exit value of the loop, to determine whether the
 800 loop should exit.  This mirrors the condition evaluation for the if/then/else
 801 statement.</p>
 802
 803 <div class="doc_code">
 804 <pre>
 805       (* Create the "after loop" block and insert it. *)
 806       let loop_end_bb = insertion_block builder in
 807       let after_bb = append_block "afterloop" the_function in
 808
 809       (* Insert the conditional branch into the end of loop_end_bb. *)
 810       ignore (build_cond_br end_cond loop_bb after_bb builder);
 811
 812       (* Any new code will be inserted in after_bb. *)
 813       position_at_end after_bb builder;
 814 </pre>
 815 </div>
 816
 817 <p>With the code for the body of the loop complete, we just need to finish up
 818 the control flow for it.  This code remembers the end block (for the phi node), then creates the block for the loop exit ("afterloop").  Based on the value of the
 819 exit condition, it creates a conditional branch that chooses between executing
 820 the loop again and exiting the loop.  Any future code is emitted in the
 821 "afterloop" block, so it sets the insertion position to it.</p>
 822
 823 <div class="doc_code">
 824 <pre>
 825       (* Add a new entry to the PHI node for the backedge. *)
 826       add_incoming (next_var, loop_end_bb) variable;
 827
 828       (* Restore the unshadowed variable. *)
 829       begin match old_val with
 830       | Some old_val -&gt; Hashtbl.add named_values var_name old_val
 831       | None -&gt; ()
 832       end;
 833
 834       (* for expr always returns 0.0. *)
 835       const_null double_type
 836 </pre>
 837 </div>
 838
 839 <p>The final code handles various cleanups: now that we have the
 840 "<tt>next_var</tt>" value, we can add the incoming value to the loop PHI node.
 841 After that, we remove the loop variable from the symbol table, so that it isn't
 842 in scope after the for loop.  Finally, code generation of the for loop always
 843 returns 0.0, so that is what we return from <tt>Codegen.codegen_expr</tt>.</p>
 844
 845 <p>With this, we conclude the "adding control flow to Kaleidoscope" chapter of
 846 the tutorial.  In this chapter we added two control flow constructs, and used
 847 them to motivate a couple of aspects of the LLVM IR that are important for
 848 front-end implementors to know.  In the next chapter of our saga, we will get
 849 a bit crazier and add <a href="OCamlLangImpl6.html">user-defined operators</a>
 850 to our poor innocent language.</p>
 851
 852 </div>
 853
 854 <!-- *********************************************************************** -->
 855 <div class="doc_section"><a name="code">Full Code Listing</a></div>
 856 <!-- *********************************************************************** -->
 857
 858 <div class="doc_text">
 859
 860 <p>
 861 Here is the complete code listing for our running example, enhanced with the
 862 if/then/else and for expressions..  To build this example, use:
 863 </p>
 864
 865 <div class="doc_code">
 866 <pre>
 867 # Compile
 868 ocamlbuild toy.byte
 869 # Run
 870 ./toy.byte
 871 </pre>
 872 </div>
 873
 874 <p>Here is the code:</p>
 875
 876 <dl>
 877 <dt>_tags:</dt>
 878 <dd class="doc_code">
 879 <pre>
 880 &lt;{lexer,parser}.ml&gt;: use_camlp4, pp(camlp4of)
 881 &lt;*.{byte,native}&gt;: g++, use_llvm, use_llvm_analysis
 882 &lt;*.{byte,native}&gt;: use_llvm_executionengine, use_llvm_target
 883 &lt;*.{byte,native}&gt;: use_llvm_scalar_opts, use_bindings
 884 </pre>
 885 </dd>
 886
 887 <dt>myocamlbuild.ml:</dt>
 888 <dd class="doc_code">
 889 <pre>
 890 open Ocamlbuild_plugin;;
 891
 892 ocaml_lib ~extern:true "llvm";;
 893 ocaml_lib ~extern:true "llvm_analysis";;
 894 ocaml_lib ~extern:true "llvm_executionengine";;
 895 ocaml_lib ~extern:true "llvm_target";;
 896 ocaml_lib ~extern:true "llvm_scalar_opts";;
 897
 898 flag ["link"; "ocaml"; "g++"] (S[A"-cc"; A"g++"]);;
 899 dep ["link"; "ocaml"; "use_bindings"] ["bindings.o"];;
 900 </pre>
 901 </dd>
 902
 903 <dt>token.ml:</dt>
 904 <dd class="doc_code">
 905 <pre>
 906 (*===----------------------------------------------------------------------===
 907  * Lexer Tokens
 908  *===----------------------------------------------------------------------===*)
 909
 910 (* The lexer returns these 'Kwd' if it is an unknown character, otherwise one of
 911  * these others for known things. *)
 912 type token =
 913   (* commands *)
 914   | Def | Extern
 915
 916   (* primary *)
 917   | Ident of string | Number of float
 918
 919   (* unknown *)
 920   | Kwd of char
 921
 922   (* control *)
 923   | If | Then | Else
 924   | For | In
 925 </pre>
 926 </dd>
 927
 928 <dt>lexer.ml:</dt>
 929 <dd class="doc_code">
 930 <pre>
 931 (*===----------------------------------------------------------------------===
 932  * Lexer
 933  *===----------------------------------------------------------------------===*)
 934
 935 let rec lex = parser
 936   (* Skip any whitespace. *)
 937   | [&lt; ' (' ' | '\n' | '\r' | '\t'); stream &gt;] -&gt; lex stream
 938
 939   (* identifier: [a-zA-Z][a-zA-Z0-9] *)
 940   | [&lt; ' ('A' .. 'Z' | 'a' .. 'z' as c); stream &gt;] -&gt;
 941       let buffer = Buffer.create 1 in
 942       Buffer.add_char buffer c;
 943       lex_ident buffer stream
 944
 945   (* number: [0-9.]+ *)
 946   | [&lt; ' ('0' .. '9' as c); stream &gt;] -&gt;
 947       let buffer = Buffer.create 1 in
 948       Buffer.add_char buffer c;
 949       lex_number buffer stream
 950
 951   (* Comment until end of line. *)
 952   | [&lt; ' ('#'); stream &gt;] -&gt;
 953       lex_comment stream
 954
 955   (* Otherwise, just return the character as its ascii value. *)
 956   | [&lt; 'c; stream &gt;] -&gt;
 957       [&lt; 'Token.Kwd c; lex stream &gt;]
 958
 959   (* end of stream. *)
 960   | [&lt; &gt;] -&gt; [&lt; &gt;]
 961
 962 and lex_number buffer = parser
 963   | [&lt; ' ('0' .. '9' | '.' as c); stream &gt;] -&gt;
 964       Buffer.add_char buffer c;
 965       lex_number buffer stream
 966   | [&lt; stream=lex &gt;] -&gt;
 967       [&lt; 'Token.Number (float_of_string (Buffer.contents buffer)); stream &gt;]
 968
 969 and lex_ident buffer = parser
 970   | [&lt; ' ('A' .. 'Z' | 'a' .. 'z' | '0' .. '9' as c); stream &gt;] -&gt;
 971       Buffer.add_char buffer c;
 972       lex_ident buffer stream
 973   | [&lt; stream=lex &gt;] -&gt;
 974       match Buffer.contents buffer with
 975       | "def" -&gt; [&lt; 'Token.Def; stream &gt;]
 976       | "extern" -&gt; [&lt; 'Token.Extern; stream &gt;]
 977       | "if" -&gt; [&lt; 'Token.If; stream &gt;]
 978       | "then" -&gt; [&lt; 'Token.Then; stream &gt;]
 979       | "else" -&gt; [&lt; 'Token.Else; stream &gt;]
 980       | "for" -&gt; [&lt; 'Token.For; stream &gt;]
 981       | "in" -&gt; [&lt; 'Token.In; stream &gt;]
 982       | id -&gt; [&lt; 'Token.Ident id; stream &gt;]
 983
 984 and lex_comment = parser
 985   | [&lt; ' ('\n'); stream=lex &gt;] -&gt; stream
 986   | [&lt; 'c; e=lex_comment &gt;] -&gt; e
 987   | [&lt; &gt;] -&gt; [&lt; &gt;]
 988 </pre>
 989 </dd>
 990
 991 <dt>ast.ml:</dt>
 992 <dd class="doc_code">
 993 <pre>
 994 (*===----------------------------------------------------------------------===
 995  * Abstract Syntax Tree (aka Parse Tree)
 996  *===----------------------------------------------------------------------===*)
 997
 998 (* expr - Base type for all expression nodes. *)
 999 type expr =
1000   (* variant for numeric literals like "1.0". *)
1001   | Number of float
1002
1003   (* variant for referencing a variable, like "a". *)
1004   | Variable of string
1005
1006   (* variant for a binary operator. *)
1007   | Binary of char * expr * expr
1008
1009   (* variant for function calls. *)
1010   | Call of string * expr array
1011
1012   (* variant for if/then/else. *)
1013   | If of expr * expr * expr
1014
1015   (* variant for for/in. *)
1016   | For of string * expr * expr * expr option * expr
1017
1018 (* proto - This type represents the "prototype" for a function, which captures
1019  * its name, and its argument names (thus implicitly the number of arguments the
1020  * function takes). *)
1021 type proto = Prototype of string * string array
1022
1023 (* func - This type represents a function definition itself. *)
1024 type func = Function of proto * expr
1025 </pre>
1026 </dd>
1027
1028 <dt>parser.ml:</dt>
1029 <dd class="doc_code">
1030 <pre>
1031 (*===---------------------------------------------------------------------===
1032  * Parser
1033  *===---------------------------------------------------------------------===*)
1034
1035 (* binop_precedence - This holds the precedence for each binary operator that is
1036  * defined *)
1037 let binop_precedence:(char, int) Hashtbl.t = Hashtbl.create 10
1038
1039 (* precedence - Get the precedence of the pending binary operator token. *)
1040 let precedence c = try Hashtbl.find binop_precedence c with Not_found -&gt; -1
1041
1042 (* primary
1043  *   ::= identifier
1044  *   ::= numberexpr
1045  *   ::= parenexpr
1046  *   ::= ifexpr
1047  *   ::= forexpr *)
1048 let rec parse_primary = parser
1049   (* numberexpr ::= number *)
1050   | [&lt; 'Token.Number n &gt;] -&gt; Ast.Number n
1051
1052   (* parenexpr ::= '(' expression ')' *)
1053   | [&lt; 'Token.Kwd '('; e=parse_expr; 'Token.Kwd ')' ?? "expected ')'" &gt;] -&gt; e
1054
1055   (* identifierexpr
1056    *   ::= identifier
1057    *   ::= identifier '(' argumentexpr ')' *)
1058   | [&lt; 'Token.Ident id; stream &gt;] -&gt;
1059       let rec parse_args accumulator = parser
1060         | [&lt; e=parse_expr; stream &gt;] -&gt;
1061             begin parser
1062               | [&lt; 'Token.Kwd ','; e=parse_args (e :: accumulator) &gt;] -&gt; e
1063               | [&lt; &gt;] -&gt; e :: accumulator
1064             end stream
1065         | [&lt; &gt;] -&gt; accumulator
1066       in
1067       let rec parse_ident id = parser
1068         (* Call. *)
1069         | [&lt; 'Token.Kwd '(';
1070              args=parse_args [];
1071              'Token.Kwd ')' ?? "expected ')'"&gt;] -&gt;
1072             Ast.Call (id, Array.of_list (List.rev args))
1073
1074         (* Simple variable ref. *)
1075         | [&lt; &gt;] -&gt; Ast.Variable id
1076       in
1077       parse_ident id stream
1078
1079   (* ifexpr ::= 'if' expr 'then' expr 'else' expr *)
1080   | [&lt; 'Token.If; c=parse_expr;
1081        'Token.Then ?? "expected 'then'"; t=parse_expr;
1082        'Token.Else ?? "expected 'else'"; e=parse_expr &gt;] -&gt;
1083       Ast.If (c, t, e)
1084
1085   (* forexpr
1086         ::= 'for' identifier '=' expr ',' expr (',' expr)? 'in' expression *)
1087   | [&lt; 'Token.For;
1088        'Token.Ident id ?? "expected identifier after for";
1089        'Token.Kwd '=' ?? "expected '=' after for";
1090        stream &gt;] -&gt;
1091       begin parser
1092         | [&lt;
1093              start=parse_expr;
1094              'Token.Kwd ',' ?? "expected ',' after for";
1095              end_=parse_expr;
1096              stream &gt;] -&gt;
1097             let step =
1098               begin parser
1099               | [&lt; 'Token.Kwd ','; step=parse_expr &gt;] -&gt; Some step
1100               | [&lt; &gt;] -&gt; None
1101               end stream
1102             in
1103             begin parser
1104             | [&lt; 'Token.In; body=parse_expr &gt;] -&gt;
1105                 Ast.For (id, start, end_, step, body)
1106             | [&lt; &gt;] -&gt;
1107                 raise (Stream.Error "expected 'in' after for")
1108             end stream
1109         | [&lt; &gt;] -&gt;
1110             raise (Stream.Error "expected '=' after for")
1111       end stream
1112
1113   | [&lt; &gt;] -&gt; raise (Stream.Error "unknown token when expecting an expression.")
1114
1115 (* binoprhs
1116  *   ::= ('+' primary)* *)
1117 and parse_bin_rhs expr_prec lhs stream =
1118   match Stream.peek stream with
1119   (* If this is a binop, find its precedence. *)
1120   | Some (Token.Kwd c) when Hashtbl.mem binop_precedence c -&gt;
1121       let token_prec = precedence c in
1122
1123       (* If this is a binop that binds at least as tightly as the current binop,
1124        * consume it, otherwise we are done. *)
1125       if token_prec &lt; expr_prec then lhs else begin
1126         (* Eat the binop. *)
1127         Stream.junk stream;
1128
1129         (* Parse the primary expression after the binary operator. *)
1130         let rhs = parse_primary stream in
1131
1132         (* Okay, we know this is a binop. *)
1133         let rhs =
1134           match Stream.peek stream with
1135           | Some (Token.Kwd c2) -&gt;
1136               (* If BinOp binds less tightly with rhs than the operator after
1137                * rhs, let the pending operator take rhs as its lhs. *)
1138               let next_prec = precedence c2 in
1139               if token_prec &lt; next_prec
1140               then parse_bin_rhs (token_prec + 1) rhs stream
1141               else rhs
1142           | _ -&gt; rhs
1143         in
1144
1145         (* Merge lhs/rhs. *)
1146         let lhs = Ast.Binary (c, lhs, rhs) in
1147         parse_bin_rhs expr_prec lhs stream
1148       end
1149   | _ -&gt; lhs
1150
1151 (* expression
1152  *   ::= primary binoprhs *)
1153 and parse_expr = parser
1154   | [&lt; lhs=parse_primary; stream &gt;] -&gt; parse_bin_rhs 0 lhs stream
1155
1156 (* prototype
1157  *   ::= id '(' id* ')' *)
1158 let parse_prototype =
1159   let rec parse_args accumulator = parser
1160     | [&lt; 'Token.Ident id; e=parse_args (id::accumulator) &gt;] -&gt; e
1161     | [&lt; &gt;] -&gt; accumulator
1162   in
1163
1164   parser
1165   | [&lt; 'Token.Ident id;
1166        'Token.Kwd '(' ?? "expected '(' in prototype";
1167        args=parse_args [];
1168        'Token.Kwd ')' ?? "expected ')' in prototype" &gt;] -&gt;
1169       (* success. *)
1170       Ast.Prototype (id, Array.of_list (List.rev args))
1171
1172   | [&lt; &gt;] -&gt;
1173       raise (Stream.Error "expected function name in prototype")
1174
1175 (* definition ::= 'def' prototype expression *)
1176 let parse_definition = parser
1177   | [&lt; 'Token.Def; p=parse_prototype; e=parse_expr &gt;] -&gt;
1178       Ast.Function (p, e)
1179
1180 (* toplevelexpr ::= expression *)
1181 let parse_toplevel = parser
1182   | [&lt; e=parse_expr &gt;] -&gt;
1183       (* Make an anonymous proto. *)
1184       Ast.Function (Ast.Prototype ("", [||]), e)
1185
1186 (*  external ::= 'extern' prototype *)
1187 let parse_extern = parser
1188   | [&lt; 'Token.Extern; e=parse_prototype &gt;] -&gt; e
1189 </pre>
1190 </dd>
1191
1192 <dt>codegen.ml:</dt>
1193 <dd class="doc_code">
1194 <pre>
1195 (*===----------------------------------------------------------------------===
1196  * Code Generation
1197  *===----------------------------------------------------------------------===*)
1198
1199 open Llvm
1200
1201 exception Error of string
1202
1203 let context = global_context ()
1204 let the_module = create_module context "my cool jit"
1205 let builder = builder context
1206 let named_values:(string, llvalue) Hashtbl.t = Hashtbl.create 10
1207
1208 let rec codegen_expr = function
1209   | Ast.Number n -&gt; const_float double_type n
1210   | Ast.Variable name -&gt;
1211       (try Hashtbl.find named_values name with
1212         | Not_found -&gt; raise (Error "unknown variable name"))
1213   | Ast.Binary (op, lhs, rhs) -&gt;
1214       let lhs_val = codegen_expr lhs in
1215       let rhs_val = codegen_expr rhs in
1216       begin
1217         match op with
1218         | '+' -&gt; build_add lhs_val rhs_val "addtmp" builder
1219         | '-' -&gt; build_sub lhs_val rhs_val "subtmp" builder
1220         | '*' -&gt; build_mul lhs_val rhs_val "multmp" builder
1221         | '&lt;' -&gt;
1222             (* Convert bool 0/1 to double 0.0 or 1.0 *)
1223             let i = build_fcmp Fcmp.Ult lhs_val rhs_val "cmptmp" builder in
1224             build_uitofp i double_type "booltmp" builder
1225         | _ -&gt; raise (Error "invalid binary operator")
1226       end
1227   | Ast.Call (callee, args) -&gt;
1228       (* Look up the name in the module table. *)
1229       let callee =
1230         match lookup_function callee the_module with
1231         | Some callee -&gt; callee
1232         | None -&gt; raise (Error "unknown function referenced")
1233       in
1234       let params = params callee in
1235
1236       (* If argument mismatch error. *)
1237       if Array.length params == Array.length args then () else
1238         raise (Error "incorrect # arguments passed");
1239       let args = Array.map codegen_expr args in
1240       build_call callee args "calltmp" builder
1241   | Ast.If (cond, then_, else_) -&gt;
1242       let cond = codegen_expr cond in
1243
1244       (* Convert condition to a bool by comparing equal to 0.0 *)
1245       let zero = const_float double_type 0.0 in
1246       let cond_val = build_fcmp Fcmp.One cond zero "ifcond" builder in
1247
1248       (* Grab the first block so that we might later add the conditional branch
1249        * to it at the end of the function. *)
1250       let start_bb = insertion_block builder in
1251       let the_function = block_parent start_bb in
1252
1253       let then_bb = append_block "then" the_function in
1254
1255       (* Emit 'then' value. *)
1256       position_at_end then_bb builder;
1257       let then_val = codegen_expr then_ in
1258
1259       (* Codegen of 'then' can change the current block, update then_bb for the
1260        * phi. We create a new name because one is used for the phi node, and the
1261        * other is used for the conditional branch. *)
1262       let new_then_bb = insertion_block builder in
1263
1264       (* Emit 'else' value. *)
1265       let else_bb = append_block "else" the_function in
1266       position_at_end else_bb builder;
1267       let else_val = codegen_expr else_ in
1268
1269       (* Codegen of 'else' can change the current block, update else_bb for the
1270        * phi. *)
1271       let new_else_bb = insertion_block builder in
1272
1273       (* Emit merge block. *)
1274       let merge_bb = append_block "ifcont" the_function in
1275       position_at_end merge_bb builder;
1276       let incoming = [(then_val, new_then_bb); (else_val, new_else_bb)] in
1277       let phi = build_phi incoming "iftmp" builder in
1278
1279       (* Return to the start block to add the conditional branch. *)
1280       position_at_end start_bb builder;
1281       ignore (build_cond_br cond_val then_bb else_bb builder);
1282
1283       (* Set a unconditional branch at the end of the 'then' block and the
1284        * 'else' block to the 'merge' block. *)
1285       position_at_end new_then_bb builder; ignore (build_br merge_bb builder);
1286       position_at_end new_else_bb builder; ignore (build_br merge_bb builder);
1287
1288       (* Finally, set the builder to the end of the merge block. *)
1289       position_at_end merge_bb builder;
1290
1291       phi
1292   | Ast.For (var_name, start, end_, step, body) -&gt;
1293       (* Emit the start code first, without 'variable' in scope. *)
1294       let start_val = codegen_expr start in
1295
1296       (* Make the new basic block for the loop header, inserting after current
1297        * block. *)
1298       let preheader_bb = insertion_block builder in
1299       let the_function = block_parent preheader_bb in
1300       let loop_bb = append_block "loop" the_function in
1301
1302       (* Insert an explicit fall through from the current block to the
1303        * loop_bb. *)
1304       ignore (build_br loop_bb builder);
1305
1306       (* Start insertion in loop_bb. *)
1307       position_at_end loop_bb builder;
1308
1309       (* Start the PHI node with an entry for start. *)
1310       let variable = build_phi [(start_val, preheader_bb)] var_name builder in
1311
1312       (* Within the loop, the variable is defined equal to the PHI node. If it
1313        * shadows an existing variable, we have to restore it, so save it
1314        * now. *)
1315       let old_val =
1316         try Some (Hashtbl.find named_values var_name) with Not_found -&gt; None
1317       in
1318       Hashtbl.add named_values var_name variable;
1319
1320       (* Emit the body of the loop.  This, like any other expr, can change the
1321        * current BB.  Note that we ignore the value computed by the body, but
1322        * don't allow an error *)
1323       ignore (codegen_expr body);
1324
1325       (* Emit the step value. *)
1326       let step_val =
1327         match step with
1328         | Some step -&gt; codegen_expr step
1329         (* If not specified, use 1.0. *)
1330         | None -&gt; const_float double_type 1.0
1331       in
1332
1333       let next_var = build_add variable step_val "nextvar" builder in
1334
1335       (* Compute the end condition. *)
1336       let end_cond = codegen_expr end_ in
1337
1338       (* Convert condition to a bool by comparing equal to 0.0. *)
1339       let zero = const_float double_type 0.0 in
1340       let end_cond = build_fcmp Fcmp.One end_cond zero "loopcond" builder in
1341
1342       (* Create the "after loop" block and insert it. *)
1343       let loop_end_bb = insertion_block builder in
1344       let after_bb = append_block "afterloop" the_function in
1345
1346       (* Insert the conditional branch into the end of loop_end_bb. *)
1347       ignore (build_cond_br end_cond loop_bb after_bb builder);
1348
1349       (* Any new code will be inserted in after_bb. *)
1350       position_at_end after_bb builder;
1351
1352       (* Add a new entry to the PHI node for the backedge. *)
1353       add_incoming (next_var, loop_end_bb) variable;
1354
1355       (* Restore the unshadowed variable. *)
1356       begin match old_val with
1357       | Some old_val -&gt; Hashtbl.add named_values var_name old_val
1358       | None -&gt; ()
1359       end;
1360
1361       (* for expr always returns 0.0. *)
1362       const_null double_type
1363
1364 let codegen_proto = function
1365   | Ast.Prototype (name, args) -&gt;
1366       (* Make the function type: double(double,double) etc. *)
1367       let doubles = Array.make (Array.length args) double_type in
1368       let ft = function_type double_type doubles in
1369       let f =
1370         match lookup_function name the_module with
1371         | None -&gt; declare_function name ft the_module
1372
1373         (* If 'f' conflicted, there was already something named 'name'. If it
1374          * has a body, don't allow redefinition or reextern. *)
1375         | Some f -&gt;
1376             (* If 'f' already has a body, reject this. *)
1377             if block_begin f &lt;&gt; At_end f then
1378               raise (Error "redefinition of function");
1379
1380             (* If 'f' took a different number of arguments, reject. *)
1381             if element_type (type_of f) &lt;&gt; ft then
1382               raise (Error "redefinition of function with different # args");
1383             f
1384       in
1385
1386       (* Set names for all arguments. *)
1387       Array.iteri (fun i a -&gt;
1388         let n = args.(i) in
1389         set_value_name n a;
1390         Hashtbl.add named_values n a;
1391       ) (params f);
1392       f
1393
1394 let codegen_func the_fpm = function
1395   | Ast.Function (proto, body) -&gt;
1396       Hashtbl.clear named_values;
1397       let the_function = codegen_proto proto in
1398
1399       (* Create a new basic block to start insertion into. *)
1400       let bb = append_block "entry" the_function in
1401       position_at_end bb builder;
1402
1403       try
1404         let ret_val = codegen_expr body in
1405
1406         (* Finish off the function. *)
1407         let _ = build_ret ret_val builder in
1408
1409         (* Validate the generated code, checking for consistency. *)
1410         Llvm_analysis.assert_valid_function the_function;
1411
1412         (* Optimize the function. *)
1413         let _ = PassManager.run_function the_function the_fpm in
1414
1415         the_function
1416       with e -&gt;
1417         delete_function the_function;
1418         raise e
1419 </pre>
1420 </dd>
1421
1422 <dt>toplevel.ml:</dt>
1423 <dd class="doc_code">
1424 <pre>
1425 (*===----------------------------------------------------------------------===
1426  * Top-Level parsing and JIT Driver
1427  *===----------------------------------------------------------------------===*)
1428
1429 open Llvm
1430 open Llvm_executionengine
1431
1432 (* top ::= definition | external | expression | ';' *)
1433 let rec main_loop the_fpm the_execution_engine stream =
1434   match Stream.peek stream with
1435   | None -&gt; ()
1436
1437   (* ignore top-level semicolons. *)
1438   | Some (Token.Kwd ';') -&gt;
1439       Stream.junk stream;
1440       main_loop the_fpm the_execution_engine stream
1441
1442   | Some token -&gt;
1443       begin
1444         try match token with
1445         | Token.Def -&gt;
1446             let e = Parser.parse_definition stream in
1447             print_endline "parsed a function definition.";
1448             dump_value (Codegen.codegen_func the_fpm e);
1449         | Token.Extern -&gt;
1450             let e = Parser.parse_extern stream in
1451             print_endline "parsed an extern.";
1452             dump_value (Codegen.codegen_proto e);
1453         | _ -&gt;
1454             (* Evaluate a top-level expression into an anonymous function. *)
1455             let e = Parser.parse_toplevel stream in
1456             print_endline "parsed a top-level expr";
1457             let the_function = Codegen.codegen_func the_fpm e in
1458             dump_value the_function;
1459
1460             (* JIT the function, returning a function pointer. *)
1461             let result = ExecutionEngine.run_function the_function [||]
1462               the_execution_engine in
1463
1464             print_string "Evaluated to ";
1465             print_float (GenericValue.as_float double_type result);
1466             print_newline ();
1467         with Stream.Error s | Codegen.Error s -&gt;
1468           (* Skip token for error recovery. *)
1469           Stream.junk stream;
1470           print_endline s;
1471       end;
1472       print_string "ready&gt; "; flush stdout;
1473       main_loop the_fpm the_execution_engine stream
1474 </pre>
1475 </dd>
1476
1477 <dt>toy.ml:</dt>
1478 <dd class="doc_code">
1479 <pre>
1480 (*===----------------------------------------------------------------------===
1481  * Main driver code.
1482  *===----------------------------------------------------------------------===*)
1483
1484 open Llvm
1485 open Llvm_executionengine
1486 open Llvm_target
1487 open Llvm_scalar_opts
1488
1489 let main () =
1490   (* Install standard binary operators.
1491    * 1 is the lowest precedence. *)
1492   Hashtbl.add Parser.binop_precedence '&lt;' 10;
1493   Hashtbl.add Parser.binop_precedence '+' 20;
1494   Hashtbl.add Parser.binop_precedence '-' 20;
1495   Hashtbl.add Parser.binop_precedence '*' 40;    (* highest. *)
1496
1497   (* Prime the first token. *)
1498   print_string "ready&gt; "; flush stdout;
1499   let stream = Lexer.lex (Stream.of_channel stdin) in
1500
1501   (* Create the JIT. *)
1502   let the_module_provider = ModuleProvider.create Codegen.the_module in
1503   let the_execution_engine = ExecutionEngine.create the_module_provider in
1504   let the_fpm = PassManager.create_function the_module_provider in
1505
1506   (* Set up the optimizer pipeline.  Start with registering info about how the
1507    * target lays out data structures. *)
1508   TargetData.add (ExecutionEngine.target_data the_execution_engine) the_fpm;
1509
1510   (* Do simple "peephole" optimizations and bit-twiddling optzn. *)
1511   add_instruction_combining the_fpm;
1512
1513   (* reassociate expressions. *)
1514   add_reassociation the_fpm;
1515
1516   (* Eliminate Common SubExpressions. *)
1517   add_gvn the_fpm;
1518
1519   (* Simplify the control flow graph (deleting unreachable blocks, etc). *)
1520   add_cfg_simplification the_fpm;
1521
1522   ignore (PassManager.initialize the_fpm);
1523
1524   (* Run the main "interpreter loop" now. *)
1525   Toplevel.main_loop the_fpm the_execution_engine stream;
1526
1527   (* Print out all the generated code. *)
1528   dump_module Codegen.the_module
1529 ;;
1530
1531 main ()
1532 </pre>
1533 </dd>
1534
1535 <dt>bindings.c</dt>
1536 <dd class="doc_code">
1537 <pre>
1538 #include &lt;stdio.h&gt;
1539
1540 /* putchard - putchar that takes a double and returns 0. */
1541 extern double putchard(double X) {
1542   putchar((char)X);
1543   return 0;
1544 }
1545 </pre>
1546 </dd>
1547 </dl>
1548
1549 <a href="OCamlLangImpl6.html">Next: Extending the language: user-defined
1550 operators</a>
1551 </div>
1552
1553 <!-- *********************************************************************** -->
1554 <hr>
1555 <address>
1556   <a href="http://jigsaw.w3.org/css-validator/check/referer"><img
1557   src="http://jigsaw.w3.org/css-validator/images/vcss" alt="Valid CSS!"></a>
1558   <a href="http://validator.w3.org/check/referer"><img
1559   src="http://www.w3.org/Icons/valid-html401" alt="Valid HTML 4.01!"></a>
1560
1561   <a href="mailto:sabre@nondot.org">Chris Lattner</a><br>
1562   <a href="mailto:idadesub@users.sourceforge.net">Erick Tryzelaar</a><br>
1563   <a href="http://llvm.org">The LLVM Compiler Infrastructure</a><br>
1564   Last modified: $Date: 2007-10-17 11:05:13 -0700 (Wed, 17 Oct 2007) $
1565 </address>
1566 </body>
1567 </html>