RetroForth, Release 6 (Revision 14)
---------------------------------------------------------------------
RetroForth is an open-source Forth development system. The system was created by Tom Novelli in 1998 and has been developed by Charles Childers since 2002.
---------------------------------------------------------------------

Included in this release:
  1) Full source code for RetroForth 6.14
     a) Native
     b) Linux
       1) Console
       2) SVGALIB
       3) SDL
     c) Incomplete
       1) Windows
       2) BeOS
  2) Optional library code
  3) Linux Services for RetroForth (LSR)
  4) Sample code
     a) String usage
     b) IF/THEN and looping demos
  5) Basic documentation
  6) Forth -> Assembly conversion

Compiling RetroForth
--------------------
1) Enter the retroforth/source directory
2) Run '. build platform [-s]' or './build platform [-s]'
   a) Platform should be either 'native' or 'linux'
   b) -s will strip debugging information out of the image

Running RetroForth
------------------
1) Enter the retroforth/source directory
2) Run './images/rf???' where ??? is the varient you want to run
   (Options are 'rf', 'rf-vga', and 'rf-sdl')

Customising RetroForth
----------------------
Edit source/user/user.f and source/user/user.asm to implement the code
specific to your application. Unless you're hacking the Forth kernel,
you don't need to touch the other files :)

Here's a simple 'hello' world example that can be pasted into
'user.f':

" hello, world!" type cr bye

OR:

" hello, world!" string: hello_msg
: hello hello_msg type cr ;
hello bye

Other samples are in the default user.f

When you run the 'rf???' binaries, the code will execute then
terminate (as defined by the 'bye' word)

I hope you enjoy using RetroForth!



Forth2Asm: A Companion to RetroForth
========================================================================
Forth2Asm is intended for two primary tasks:

  1) Securing your source code
  2) Reducing bloat in RetroForth Applications

By converting your source code into assembly, you can easily compile
the results into a RetroForth kernel without worry about others seeing
your source code.

To reduce the bloat, Forth2Asm also eliminates the need for the
interpreter / compiler that is normally included with RetroForth.

There is another benefit in that the assembled code is faster than
running from withing RetroForth, though that doesn't matter much on
today's computers.
========================================================================
Forth2Asm is not ready for general use! Please use with caution and
expect problems to abound!

Don't use strings, they break the code really badly. Also, prefix every interpreted statement by a single space to make sure they are 'call'ed or 'upsh'ed as neccessary.

If you make any improvements, please send them in!

Requires: sed, RetroForth 6, bash is helpful
========================================================================
.log
6/26/2003
I started the project yesterday, coding a minimal skeleton. Today I'm
extending it and working to make it generate working programs.

Right now this will generate valid assembly, compile it, and link it.
There are problems: it can't run the outputted code. It always
segfaults, so I need to work out why, then fix it. I copied a few
primitives from Retro6-linux over. Even without them it segfaults. I'll
have to keep working to find out why.

>> The segfaults occur when values are PUSH'd to the stack. I'd like to
>> use the hardware stack (via the PUSH/POP instructions) if possible.
>> I'll have to look into why this occurs.

I'm now adding the ability to have comments (not on the same line as
code!)

>> Finished. This makes it easier to document the Forth code.

The primitives aren't quite working yet either... I'll have to fix the
stack bugs before I can correct them.


7/5/2003
Moved the entire SED part of the code into a separate file
Now store temporary files in /tmp, remove them when done
Decimal numbers no longer require prefixing
Reverted to RF6-style primitives (using macros, etc)
Will be adding call tables and easily changable register usage soon


7/12/2003
Fixed bug in prefixing code, extended documentation.


8/12/2003
Expanded the README with a short introduction. Included Forth2Asm in
RetroForth releases starting with 6.11
Comment filtering dropped for now.

8/13/2003
Replaced 'forthc' with a simple wrapper to the SED script that actually does the conversion. As long as you only use supported features, you can put the resulting code in user.asm to build an application.

Comment filtering works again.
