basis/compiler/compiler-docs.factor

   1 USING: compiler.generator help.markup help.syntax words io parser
   2 assocs words.private sequences compiler.units ;
   3 IN: compiler
   4
   5 HELP: enable-compiler
   6 { $description "Enables the optimizing compiler." } ;
   7
   8 HELP: disable-compiler
   9 { $description "Enables the optimizing compiler." } ;
  10
  11 ARTICLE: "compiler-usage" "Calling the optimizing compiler"
  12 "Normally, new word definitions are recompiled automatically. This can be changed:"
  13 { $subsection disable-compiler }
  14 { $subsection enable-compiler }
  15 "The optimizing compiler can be called directly, although this should not be necessary under normal circumstances:"
  16 { $subsection optimized-recompile-hook }
  17 "Removing a word's optimized definition:"
  18 { $subsection decompile }
  19 "Higher-level words can be found in " { $link "compilation-units" } "." ;
  20
  21 ARTICLE: "compiler" "Optimizing compiler"
  22 "Factor is a fully compiled language implementation with two distinct compilers:"
  23 { $list
  24     { "The " { $emphasis "non-optimizing quotation compiler" } " compiles quotations to naive machine code very quickly. The non-optimizing quotation compiler is part of the VM." }
  25     { "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." }
  26 }
  27 "The optimizing compiler only compiles words which have a static stack effect. This means that methods defined on fundamental generic words such as " { $link nth } " should have a static stack effect; for otherwise, most of the system would be compiled with the non-optimizing compiler. See " { $link "inference" } " and " { $link "cookbook-pitfalls" } "."
  28 { $subsection "compiler-usage" }
  29 { $subsection "compiler-errors" }
  30 { $subsection "hints" }
  31 { $subsection "generator" } ;
  32
  33 ABOUT: "compiler"
  34
  35 HELP: decompile
  36 { $values { "word" word } }
  37 { $description "Removes a word's optimized definition. The word will be compiled with the non-optimizing compiler until recompiled with the optimizing compiler again." } ;
  38
  39 HELP: (compile)
  40 { $values { "word" word } }
  41 { $description "Compile a single word." }
  42 { $notes "This is an internal word, and user code should call " { $link compile } " instead." } ;
  43
  44 HELP: optimized-recompile-hook
  45 { $values { "words" "a sequence of words" } { "alist" "an association list" } }
  46 { $description "Compile a set of words." }
  47 { $notes "This is an internal word, and user code should call " { $link compile } " instead." } ;