114 lines
6.1 KiB
Factor
Executable File
114 lines
6.1 KiB
Factor
Executable File
USING: generator help.markup help.syntax words io parser
|
|
assocs words.private sequences ;
|
|
IN: compiler
|
|
|
|
ARTICLE: "compiler-usage" "Calling the optimizing compiler"
|
|
"The main entry point to the optimizing compiler is a single word taking a word as input:"
|
|
{ $subsection compile }
|
|
"The optimizing compiler can also compile a single quotation:"
|
|
{ $subsection compile-quot }
|
|
{ $subsection compile-call }
|
|
"Three utility words for bulk compilation:"
|
|
{ $subsection compile-batch }
|
|
{ $subsection compile-vocabs }
|
|
"Bulk compilation saves compile warnings and errors in a global variable, instead of printing them as they arise:"
|
|
{ $subsection compile-errors }
|
|
"The warnings and errors can be viewed later:"
|
|
{ $subsection :warnings }
|
|
{ $subsection :errors }
|
|
{ $subsection forget-errors } ;
|
|
|
|
ARTICLE: "recompile" "Automatic recompilation"
|
|
"When a word is redefined, you can recompile all affected words automatically:"
|
|
{ $subsection recompile } ;
|
|
|
|
ARTICLE: "compiler" "Optimizing compiler"
|
|
"Factor is a fully compiled language implementation with two distinct compilers:"
|
|
{ $list
|
|
{ "The " { $emphasis "non-optimizing quotation compiler" } " compiles quotations to naive machine code very quickly. The non-optimizing quotation compiler is part of the VM." }
|
|
{ "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." }
|
|
}
|
|
"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:"
|
|
{ $list
|
|
{ "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" } "." }
|
|
{ "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." }
|
|
}
|
|
{ $subsection "compiler-usage" }
|
|
{ $subsection "recompile" } ;
|
|
|
|
ABOUT: "compiler"
|
|
|
|
HELP: compile-error
|
|
{ $values { "word" word } { "error" "an error" } }
|
|
{ $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." } ;
|
|
|
|
HELP: begin-batch
|
|
{ $values { "seq" "a sequence of words" } }
|
|
{ $description "Begins batch compilation. Any compile errors reported until a call to " { $link end-batch } " are stored in the " { $link compile-errors } " global variable." }
|
|
$low-level-note ;
|
|
|
|
HELP: compile-error.
|
|
{ $values { "pair" "a " { $snippet "{ word error }" } " pair" } }
|
|
{ $description "Prints a compiler error to the " { $link stdio } " stream." } ;
|
|
|
|
HELP: (:errors)
|
|
{ $values { "seq" "an alist" } }
|
|
{ $description "Outputs all serious compiler errors from the most recent compile batch as a sequence of " { $snippet "{ word error }" } " pairs." } ;
|
|
|
|
HELP: :errors
|
|
{ $description "Prints all serious compiler errors from the most recent compile batch to the " { $link stdio } " stream." } ;
|
|
|
|
HELP: (:warnings)
|
|
{ $values { "seq" "an alist" } }
|
|
{ $description "Outputs all ignorable compiler warnings from the most recent compile batch as a sequence of " { $snippet "{ word error }" } " pairs." } ;
|
|
|
|
HELP: :warnings
|
|
{ $description "Prints all ignorable compiler warnings from the most recent compile batch to the " { $link stdio } " stream." } ;
|
|
|
|
HELP: end-batch
|
|
{ $description "Ends batch compilation, printing a summary of the errors and warnings produced to the " { $link stdio } " stream." }
|
|
$low-level-note ;
|
|
|
|
HELP: compile
|
|
{ $values { "word" word } }
|
|
{ $description "Compiles a word together with any uncompiled dependencies. Does nothing if the word is already compiled." } ;
|
|
|
|
HELP: compile-failed
|
|
{ $values { "word" word } { "error" "an error" } }
|
|
{ $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 } "." } ;
|
|
|
|
HELP: compile-batch
|
|
{ $values { "seq" "a sequence of words" } }
|
|
{ $description "Compiles a batch of words. Any compile errors are summarized at the end and can be viewed with " { $link :warnings } " and " { $link :errors } "." } ;
|
|
|
|
{ :errors (:errors) :warnings (:warnings) } related-words
|
|
|
|
HELP: compile-vocabs
|
|
{ $values { "seq" "a sequence of strings" } }
|
|
{ $description "Compiles all words which have not been compiled yet from the given vocabularies." } ;
|
|
|
|
HELP: compile-quot
|
|
{ $values { "quot" "a quotation" } { "word" "a new, uninterned word" } }
|
|
{ $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 } "." }
|
|
{ $errors "Throws an error if the stack effect of the quotation cannot be inferred." } ;
|
|
|
|
HELP: compile-call
|
|
{ $values { "quot" "a quotation" } }
|
|
{ $description "Compiles and runs a quotation." }
|
|
{ $errors "Throws an error if the stack effect of the quotation cannot be inferred." } ;
|
|
|
|
HELP: recompile
|
|
{ $description "Recompiles words whose compiled definitions have become out of date as a result of dependent words being redefined." } ;
|
|
|
|
HELP: compile-all
|
|
{ $description "Recompiles all words." } ;
|
|
|
|
HELP: compile-begins
|
|
{ $values { "word" word } }
|
|
{ $description "Prints a message stating the word is being compiled, unless we are inside a " { $link compile-batch } "." } ;
|
|
|
|
HELP: (compile)
|
|
{ $values { "word" word } }
|
|
{ $description "Compile a single word." }
|
|
{ $notes "This is an internal word, and user code should call " { $link compile } " instead." } ;
|