basis/compiler/compiler-docs.factor

   1 USING: assocs compiler.cfg compiler.cfg.builder compiler.cfg.optimizer
   2 compiler.errors compiler.tree.builder compiler.tree.optimizer
   3 compiler.units compiler.codegen help.markup help.syntax io
   4 parser quotations sequences words ;
   5 IN: compiler
   6
   7 HELP: enable-optimizer
   8 { $description "Enables the optimizing compiler." } ;
   9
  10 HELP: disable-optimizer
  11 { $description "Disable the optimizing compiler." } ;
  12
  13 ARTICLE: "compiler-usage" "Calling the optimizing compiler"
  14 "Normally, new word definitions are recompiled automatically. This can be changed:"
  15 { $subsections
  16     disable-optimizer
  17     enable-optimizer
  18 }
  19 "More words can be found in " { $link "compilation-units" } "." ;
  20
  21 ARTICLE: "compiler-impl" "Compiler implementation"
  22 "The " { $vocab-link "compiler" } " vocabulary, in addition to providing the user-visible words of the compiler, implements the main compilation loop."
  23 $nl
  24 "Once compiled, a word is added to the assoc stored in the " { $link compiled } " variable. When compilation is complete, this assoc is passed to " { $link modify-code-heap } "."
  25 $nl
  26 "The " { $link compile-word } " word performs the actual task of compiling an individual word. The process proceeds as follows:"
  27 { $list
  28   { "The " { $link frontend } " word calls " { $link build-tree } ". If this fails, the error is passed to " { $link deoptimize } ". The logic for ignoring certain compile errors generated for inline words and macros is located here. If the error is not ignorable, it is added to the global " { $link compiler-errors } " assoc (see " { $link "compiler-errors" } ")." }
  29   { "If the word contains a breakpoint, compilation ends here. Otherwise, all remaining steps execute until machine code is generated. Any further errors thrown by the compiler are not reported as compile errors, but instead are ordinary exceptions. This is because they indicate bugs in the compiler, not errors in user code." }
  30   { "The " { $link frontend } " word then calls " { $link optimize-tree } ". This produces the final optimized tree IR, and this stage of the compiler is complete." }
  31   { "The " { $link backend } " word calls " { $link build-cfg } " followed by " { $link optimize-cfg } " and a few other stages. Finally, it calls " { $link generate } "." }
  32 }
  33 "If compilation fails, the word is stored in the " { $link compiled } " assoc with a value of " { $link f } ". This causes the VM to compile the word with the non-optimizing compiler."
  34 $nl
  35 "Calling " { $link modify-code-heap } " is handled not by the " { $vocab-link "compiler" } " vocabulary, but rather " { $vocab-link "compiler.units" } ". The optimizing compiler merely provides an implementation of the " { $link recompile } " generic word." ;
  36
  37 ARTICLE: "compiler" "Optimizing compiler"
  38 "Factor includes two compilers which work behind the scenes. Words are always compiled, and the compilers do not have to be invoked explicitly. For the most part, compilation is fully transparent. However, there are a few things worth knowing about the compilation process."
  39 $nl
  40 "The two compilers differ in the level of analysis they perform:"
  41 { $list
  42     { "The " { $emphasis "non-optimizing quotation compiler" } " compiles quotations to naive machine code very quickly. The non-optimizing quotation compiler is part of the VM." }
  43     { "The " { $emphasis "optimizing word compiler" } " compiles whole words at a time while performing extensive data and control flow analysis. This provides greater performance for generated code, but incurs a much longer compile time. The optimizing compiler is written in Factor." }
  44 }
  45 "The optimizing compiler also trades off compile time for performance of generated code, so loading certain vocabularies might take a while. Saving the image after loading vocabularies can save you a lot of time that you would spend waiting for the same code to load in every coding session; see " { $link "images" } " for information."
  46 $nl
  47 "Most code you write will run with the optimizing compiler. Sometimes, the non-optimizing compiler is used, for example for listener interactions, or for running the quotation passed to " { $link POSTPONE: call( } "."
  48 { $subsections
  49     "compiler-errors"
  50     "hints"
  51     "compiler-usage"
  52     "compiler-impl"
  53 } ;
  54
  55 ABOUT: "compiler"
  56
  57 HELP: frontend
  58 { $values { "word" word } { "tree" sequence } }
  59 { $description "First step of the compilation process. It outputs a high-level tree in SSA form." } ;
  60
  61 HELP: backend
  62 { $values { "tree" "a " { $link sequence } " of SSA nodes" } { "word" word } }
  63 { $description "The second last step of the compilation process. A word and its SSA tree is taken as input and a " { $link cfg } " is built from which assembly code is generated." }
  64 { $see-also generate } ;
  65
  66 HELP: compiled
  67 { $var-description { "An " { $link assoc } " used by the optimizing compiler for intermediate storage of generated code. The keys are the labels to the CFG:s and the values the generated code as described by the " { $link generate } " word." } } ;
  68
  69 HELP: compile-word
  70 { $values { "word" word } }
  71 { $description "Compile a single word." }
  72 { $notes "This is an internal word, and user code should call " { $link compile } " instead." } ;
  73
  74 HELP: optimizing-compiler
  75 { $description "Singleton class implementing " { $link recompile } " to call the optimizing compiler." }
  76 { $notes "This is an internal word, and user code should call " { $link compile } " instead." } ;