RetroForth 6.22                                       http://www.retroforth.org
-------------------------------------------------------------------------------
This is *not* an official build of RetroForth 6.22. It is an early
patch to show where development is at and get feedback from the
users. Use at your own risk.


Section 1: What's New
-------------------------------------------------------------------------------
This is primarily a maintainence/debugging release. It cleans up some of the 
codebase and provides few new features. Most users will want to upgrade anyway.

I. Build system changes
  A. Generates symlinks for Forth core
  B. Generates a printable/searchable listing of errors (ERRORLOG)
  C. Cleaner output
  D. Added "dist-clean" option to completely old executables
II. Bugfixes
  A. Using .s on an under/overflowed stack no longer crashes.
III. New or Changed words
  A. octal, binary
IV. Removed words
V. Ports
  A. The forth core (forth.f, forth.asm, forth-ic.asm) is now
     symlinked into each port's directory.
  B. User.asm and user.f have been dropped since no one uses them



Section 2: Building the images
-------------------------------------------------------------------------------
As normal, gunzip and detar the source package.

     bash# tar xzf retroforth-6.22.tar.gz

Then enter the directory and type 'make'

     bash# cd retroforth
     bash# make

Check ERRORLOG to see if any problems were encountered during the
build. The "clean" function is now invoked at the end of each build cycle.


Section 3: Notes, comments, bugs
-------------------------------------------------------------------------------
You must have NASM and/or FASM (recent versions of each!) to build RetroForth.
NASM will build Linux versions (console, svgalib, libSDL) and FASM will build
both Linux and Windows versions (console only). To build the svgalib and
libSDL versions you'll also need GCC or TCC and the libraries. The build
process assumes a POSIX-like environment, so take that into account as well.

Please report any bugs by visiting http://forum.retroforth.org. I'll try to
fix them quickly. Feature requests are welcome too.


Section 4: File Organization
-------------------------------------------------------------------------------
retro.asm      Main file, includes all others
macros         Macros for internal use (dictionary, stack)
forth.asm      Forth dictionary + primitives
forth-ic.asm   Forth Interpreter/Compiler
forth.f        High-level Forth words
drivers.asm    Platform specific drivers, assembly
drivers.f      Platform specific drivers, Forth
----------------------------------------------------------
Each version is saved into a subdirectory under
retroforth/ports. The forth* files are stored one level
above this (../) and can be used with either NASM or FASM.
They are symlinked into each port's directory though.
----------------------------------------------------------
If you are editing RETRO.ASM, make sure that the files are
included in this order:

1) forth-ic.asm
2) drivers.asm
3) forth.asm

And don't forget to INCBIN or FILE the following files in
this order:

1) forth.f
2) drivers.f
----------------------------------------------------------


Section 5: Register Usage
-------------------------------------------------------------------------------
EAX	TOS			|
EBX				|
ECX				|
EDX				|
ESI	Pointer to TOS		| Initally set to sp0
EDI				|
ESP	Return Stack		|
EBP				|


Section 6: Dictionary Structure
-------------------------------------------------------------------------------
c: dd link_to_previous_word
   dd pointer_to_cfa
   db length_of_name
   db "name"
b: ... assembly code ...
   ret

c: dd link_to_previous_word
   dd pointer_to_cfa
   db length_of_name
   db "name"
b: ... assembly code ...
   ret
