core/compiler/compiler-docs.factor

   1 USING: generator help.markup help.syntax words io parser
   2 assocs words.private sequences ;
   3 IN: compiler
   4
   5 ARTICLE: "compiler-usage" "Calling the optimizing compiler"
   6 "The main entry point to the optimizing compiler is a single word taking a word as input:"
   7 { $subsection compile }
   8 "The above word throws an error if the word did not compile. Another variant simply prints the error and returns:"
   9 { $subsection try-compile }
  10 "The optimizing compiler can also compile a single quotation:"
  11 { $subsection compile-quot }
  12 { $subsection compile-1 }
  13 "Three utility words for bulk compilation:"
  14 { $subsection compile-batch }
  15 { $subsection compile-vocabs }
  16 { $subsection compile-all }
  17 "Bulk compilation saves compile warnings and errors in a global variable, instead of printing them as they arise:"
  18 { $subsection compile-errors }
  19 "The warnings and errors can be viewed later:"
  20 { $subsection :warnings }
  21 { $subsection :errors }
  22 { $subsection forget-errors } ;
  23
  24 ARTICLE: "recompile" "Automatic recompilation"
  25 "When a word is redefined, you can recompile all affected words automatically:"
  26 { $subsection recompile }
  27 "Normally loading a source file or a module also calls " { $link recompile } ". This can be disabled by wrapping file loading in a combinator:"
  28 { $subsection no-parse-hook } ;
  29
  30 ARTICLE: "compiler" "Optimizing compiler"
  31 "Factor is a fully compiled language implementation with two distinct compilers:"
  32 { $list
  33     { "The " { $emphasis "non-optimizing quotation compiler" } " compiles quotations to naive machine code very quickly. The non-optimizing quotation compiler is part of the VM." }
  34     { "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." }
  35 }
  36 "While the quotation compiler is transparent to the developer, the optimizing compiler is invoked explicitly. It differs in two important ways from the non-optimizing compiler:"
  37 { $list
  38     { "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" } "." }
  39     { "The optimizing compiler performs " { $emphasis "early binding" } "; if a compiled word " { $snippet "A" } " calls another compiled word " { $snippet "B" } " and " { $snippet "B" } " is subsequently redefined, the compiled definition of " { $snippet "A" } " will still refer to the earlier compiled definition of " { $snippet "B" } ", until " { $snippet "A" } " explicitly recompiled." }
  40 }
  41 { $subsection "compiler-usage" }
  42 { $subsection "recompile" } ;
  43
  44 ABOUT: "compiler"
  45
  46 HELP: compile-error
  47 { $values { "word" word } { "error" "an error" } }
  48 { $description "If inside a " { $link compile-batch } ", saves the error for future persual via " { $link :errors } " and " { $link :warnings } ", otherwise reports the error to the " { $link stdio } " stream." } ;
  49
  50 HELP: begin-batch
  51 { $values { "seq" "a sequence of words" } }
  52 { $description "Begins batch compilation. Any compile errors reported until a call to " { $link end-batch } " are stored in the " { $link compile-errors } " global variable." }
  53 $low-level-note ;
  54
  55 HELP: compile-error.
  56 { $values { "pair" "a " { $snippet "{ word error }" } " pair" } }
  57 { $description "Prints a compiler error to the " { $link stdio } " stream." } ;
  58
  59 HELP: (:errors)
  60 { $values { "seq" "an alist" } }
  61 { $description "Outputs all serious compiler errors from the most recent compile batch as a sequence of " { $snippet "{ word error }" } " pairs."  } ;
  62
  63 HELP: :errors
  64 { $description "Prints all serious compiler errors from the most recent compile batch to the " { $link stdio } " stream." } ;
  65
  66 HELP: (:warnings)
  67 { $values { "seq" "an alist" } }
  68 { $description "Outputs all ignorable compiler warnings from the most recent compile batch as a sequence of " { $snippet "{ word error }" } " pairs."  } ;
  69
  70 HELP: :warnings
  71 { $description "Prints all ignorable compiler warnings from the most recent compile batch to the " { $link stdio } " stream." } ;
  72
  73 HELP: end-batch
  74 { $description "Ends batch compilation, printing a summary of the errors and warnings produced to the " { $link stdio } " stream." }
  75 $low-level-note ;
  76
  77 HELP: compile
  78 { $values { "word" word } }
  79 { $description "Compiles a word together with any uncompiled dependencies. Does nothing if the word is already compiled." }
  80 { $errors "If compilation fails, this word can throw an error. In particular, if the word's stack effect cannot be inferred, this word will throw an error. The related " { $link try-compile } " word logs errors and returns rather than throwing." } ;
  81
  82 HELP: compile-failed
  83 { $values { "word" word } { "error" "an error" } }
  84 { $description "Called when the optimizing compiler fails to compile a word. The word is removed from the set of words pending compilation, and it's un-optimized compiled definition will be used. The error is reported by calling " { $link compile-error } "." } ;
  85
  86 HELP: try-compile
  87 { $values { "word" word } }
  88 { $description "Compiles a word together with any uncompiled dependencies. Does nothing if the word is already compiled." }
  89 { $errors "If compilation fails, this calls " { $link compile-failed } "." } ;
  90
  91 HELP: forget-errors
  92 { $values { "seq" "a sequence of words" } }
  93 { $description "If any of the words in the sequence previously failed to compile, removes the marker indicating such."
  94 $nl
  95 "The compiler remembers which words failed to compile as an optimization, so that it does not try to infer the stack effect of words which do not have one over and over again." }
  96 { $notes "Usually this word does not need to be called directly; if a word failed to compile because of a stack effect error, fixing the word definition clears the flag automatically. However, if words failed to compile due to external factors which were subsequently rectified, such as an unavailable C library or a missing or broken compiler transform, this flag can be cleared for all words:"
  97 { $code "all-words forget-errors" }
  98 "Subsequent invocations of the compiler will consider all words for compilation." } ;
  99
 100 HELP: compile-batch
 101 { $values { "seq" "a sequence of words" } }
 102 { $description "Compiles a batch of words. Any compile errors are summarized at the end and can be viewed with " { $link :warnings } " and " { $link :errors } "." } ;
 103
 104 { :errors (:errors) :warnings (:warnings) } related-words
 105
 106 HELP: compile-vocabs
 107 { $values { "seq" "a sequence of strings" } }
 108 { $description "Compiles all words which have not been compiled yet from the given vocabularies." } ;
 109
 110 HELP: compile-quot
 111 { $values { "quot" "a quotation" } { "word" "a new, uninterned word" } }
 112 { $description "Creates a new uninterned word having the given quotation as its definition, and compiles it. The returned word can be passed to " { $link execute } "." }
 113 { $errors "Throws an error if the stack effect of the quotation cannot be inferred." } ;
 114
 115 HELP: compile-1
 116 { $values { "quot" "a quotation" } }
 117 { $description "Compiles and runs a quotation." }
 118 { $errors "Throws an error if the stack effect of the quotation cannot be inferred." } ;
 119
 120 HELP: recompile
 121 { $description "Recompiles words whose compiled definitions have become out of date as a result of dependent words being redefined." } ;
 122
 123 HELP: compile-all
 124 { $description "Compiles all words which have not been compiled yet." } ;
 125
 126 HELP: recompile-all
 127 { $description "Recompiles all words." } ;
 128
 129 HELP: changed-words
 130 { $var-description "Global variable holding words which need to be recompiled. Implemented as a hashtable where a key equals its value. This hashtable is updated by " { $link define } " when words are redefined, and inspected and cleared by " { $link recompile } "." } ;
 131
 132 HELP: compile-begins
 133 { $values { "word" word } }
 134 { $description "Prints a message stating the word is being compiled, unless we are inside a " { $link compile-batch } "." } ;
 135
 136 HELP: (compile)
 137 { $values { "word" word } }
 138 { $description "Compile a word. This word recursively calls itself to compile all dependencies." }
 139 { $notes "This is an internal word, and user code should call " { $link compile } " instead." } ;