The Retro/Forth Metacompiler
----------------------------
A metacompiler is used to compiler a compiler; a compiler-compiler.
Retro's metacompiler compiles a Forth compiler that includes an operating
system kernel (an exokernel, to be exact).  It's capable of cross-compiling
from one platform to another, as long as the target's cell size is no larger
than the host's, otherwise modifications will be required.  My first
metacompilation of Retro was from gForth under Unix to the "bare iron"
80386.

An assembler is also required to compile the "primitive" words from which
the other words are built, unless the primitives are written in machine code
(which is easy on Forth/MISC chips like the F21 and the Novix).  An existing
assembler may be used, maybe with some modifications.


Now for an explanation of the metacompiler words - there's not much to it,
but it's important to understand exactly how it works.


tSTATE			Variable: the metacompiler's equivalent to STATE
[[			Temporarily stops metacompilation (tSTATE=0)
]]			Resumes metacompilation (tSTATE=1)

tLIT (x "name" -)	Creates a literal (constant)
tVAR ("name" -)		Creates a variable initialized to 0
tVAL (x "name" -)	Creates a variable initialized to x

	Words created with tLIT behave as ordinary constants when used
	outside of a T: definition.  Words created with tVAR and tVAL return
	a *target* address; you can use that address in assembly code.


T: ( "name" -)		Begins compiling a target word.
;T			Ends the definition.

	For each word in a T: definition, first the TARGET vocabulary is
	searched, then META, then ASSEMBLER, then FORTH.  If the word is
	found, it will be executed, otherwise it will be converted to a
	number, or if that fails, "error - unknown word".  Numbers are
	compiled if tSTATE is 1, otherwise they are left on the stack. 
	TARGET words will also be compiled only if tSTATE is 1, otherwise
	they behave conveniently for metacompiling.

	Use [[ and ]] to prevent words from being compiled.  This is
	necessary for inline assembly, amongst other things.


{ 			Don't search TARGET
}			Do search TARGET


TCODE: ( "name" -)	Defines an assembly language primitive.
;TCODE			Ends the definition.

	TCODE: is used mainly for low-level primitives.  tSTATE is set to 0,
	so target words behave differently: Constants push their value,
	variables push their PFA, and T: and tCODE: words push their CFA.
	For mixed Forth/Assembler code it's easier to use T: with [[ and ]].

	Note: tCODE: is only used for targets that are complex enough to
	need an assembler.
