From a69d404f743a0ef40e1d0c084fcefe0ec833223c Mon Sep 17 00:00:00 2001 From: Slava Pestov Date: Thu, 16 Apr 2009 16:24:14 -0500 Subject: [PATCH] Start documenting compiler internals --- basis/compiler/compiler-docs.factor | 27 ++++++++++++++++++++++++--- 1 file changed, 24 insertions(+), 3 deletions(-) diff --git a/basis/compiler/compiler-docs.factor b/basis/compiler/compiler-docs.factor index f19225a45c..f92f0015d3 100644 --- a/basis/compiler/compiler-docs.factor +++ b/basis/compiler/compiler-docs.factor @@ -1,5 +1,7 @@ -USING: help.markup help.syntax words io parser -assocs words.private sequences compiler.units quotations ; +USING: assocs compiler.cfg.builder compiler.cfg.optimizer +compiler.errors compiler.tree.builder compiler.tree.optimizer +compiler.units help.markup help.syntax io parser quotations +sequences words words.private ; IN: compiler HELP: enable-compiler @@ -18,6 +20,24 @@ ARTICLE: "compiler-usage" "Calling the optimizing compiler" { $subsection compile-call } "Higher-level words can be found in " { $link "compilation-units" } "." ; +ARTICLE: "compiler-impl" "Compiler implementation" +"The " { $vocab-link "compiler" } "vocabulary, in addition to providing the user-visible words of the compiler, implements the main compilation loop." +$nl +"Words are added to the " { $link compile-queue } " variable as needed and compiled." +{ $subsection compile-queue } +"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 } "." +$nl +"The " { $link (compile) } " word performs the actual task of compiling an individual word. The process proceeds as follows:" +{ $list + { "The " { $link frontend } " word calls " { $link build-tree-from-word } ". If this fails, the error is passed to " { $link fail } ". The logic for ignoring compile warnings 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" } ")." } + { "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." } + { "The " { $link frontend } " word then calls " { $link optimize-tree } ". This produces the final optimized tree IR, and this stage of the compiler is complete." } + { "The " { $link backend } " word calls " { $link build-cfg } " followed by " { $link optimize-cfg } " and a few other stages. Finally, it calls " { $link save-asm } ", and adds any uncompiled words called by this word to the compilation queue with " { $link maybe-compile } "." } +} +"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." +$nl +"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." ; + ARTICLE: "compiler" "Optimizing compiler" "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." $nl @@ -31,7 +51,8 @@ $nl "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." { $subsection "compiler-errors" } { $subsection "hints" } -{ $subsection "compiler-usage" } ; +{ $subsection "compiler-usage" } +{ $subsection "compiler-impl" } ; ABOUT: "compiler"