SEDForth: A Forth Compiler in SED
Copyright (c)2003 Charles Childers

You may freely modify and/or distribute this program as long as you do
not remove this notice from any copies. There is no warranty on this
software. Use at your own risk.
------------------------------------------------------------------------------
Release 0.0.4 of SEDForth brings many improvements to the system.
Variables, comments, and renaming of words now work properly. Basic
string support, second stack, multiple file compilation, optional
extensions from RetroForth, and an inline assembler have been added.

This release also adds several new, but very buggy, features. It is now 
possible to compile Forth into a Linux kernel module. Additionally,
there is now an indirect calling convention that can be configured at
compile time. These are optional and disabled by default.
------------------------------------------------------------------------------
Todo
 * Use RetroForth primitives and macros when possible (change 'code', etc)
 * Get module generation working!
   * Look at stack initialization
   * Sometimes I get paging errors, find the cause of these
 * More documentation, reorganize this file.
------------------------------------------------------------------------------

Why write a Forth in SED?
   Because I can! Seriously, I started this as a tool to go along with
   RetroForth 6.1x, but it's begun to spin off into a completely
   separate tool. Originally it was intended to help convert Forth code
   into assembly that could be linked with the RetroForth kernel. Now it
   can generate runnable applications using a modified version of the RF
   primitives.

   I'm writing it for my own use, though I am also releasing it to the
   world so others can use it if they want to.

What do I need to use it?
   * An implementation of SED (I'm using GNU SED 3.02 at the moment)
   * A recent version of NASM (http://nasm.sf.net)
   * A linux system :)
   * The 'ld' program from the GNU project (you probably have this
     already)

How does it work?
   SEDForth converts Forth code into subroutine threaded assembly. A
   simple example:

   : 1+1 1 1 + ;

   Becomes:

   oneplus1
      upsh 1
      upsh 1
      call plus
   ret

   Most conversions are fairly simple; some (like VARIABLE) are a little
   more complex.

Does it work on [INSERT ARCHITECTURE or OS HERE]?
   Currently SEDForth only generates applications for x86 Linux. This is
   expected to change! I am starting work on an ARM Linux version
   (intended mainly for use on Sharp's Zaurus PDA) and plan to develop
   versions for other operating systems as well.

How complete is it?
   Depends on how you look at it. It works fairly well, but many things
   you are used to are still missing.

   I actually hope to have it to a mostly usable state by January 2004.
   This will still leave a lot of work to be done, but hopefully will
   provide a clean basis for future development.

How are variables handled?
   The line:

   variable name

   is translated to:

   : name dovar

   Which is then converted into this assembly:

   code name
     call dovar
     dd 0

Can it still be used to generate the 'user.asm' file for RetroForth?
   Yes. Use the 'forth2asm' script instead of the 'sedforth' script.

Fallthrough between words:
   If you don't use a ; at the end of a word, executation will fall into
   the next word. See test.f for an example of this. This can be very
   useful if you know what you're doing.

Where is it going?
   SEDForth is currently aiming to be useful for developing small
   applications in Forth. Eventually, it will go beyond that. I'd like
   to use it to develop kernel modules (for linux), and maybe as a basis
   for RetroForth 7, but that's still a long way off.

It doesn't have [INSERT WORD HERE]!
   Check the extend.f file to see if it's been implemented yet. I'm
   following the RetroForth model of having just a handful of
   primitives, so chances are you'll need to include extend.f to do
   anything useful.

How do I include extend.f?
   ./sedforth FILE /path/to/extend.f

   You can have up to five files on the command line, including extend.f

Is there an assembler?
   Yes. It is based on RASM v6 (from RetroForth), but has several
   simplifications.

   : name code[ $byte $byte ... ]code ;

   You should NOT comma in the bytes. This is done automatically during
   compilation.

How do I use it?
   Decompress the source. It's hardcoded to be put in a sedforth
   directory under your home directory. If it isn't there, it won't work
   properly.

   Enter this directory and run one of the scripts on your source:
     bash# ./sedforth test.f             | Convert and compile the code
     bash# ./forth2asm test.f            | Convert the code, no skeleton
     bash# ./forth2module module.f       | Convert and compile into module

   Then you can run 'a.out' to try the program generated. If you try
   your hand at making a kernel module, you'll probably run into trouble.
   That's still very unstable.
 
Good luck and happy coding.
