                             RetroForth Manual


About This File

This will become a complete manual for RetroForth. Sadly it is incomplete. One day it will be finished, but that day has not yet come. The information in here so far is a rehash of the information found in all of the earlier documentation for RetroForth. Accuracy is not guaranteed, but is improving! If you have any additions or corrections, please feel free to post them.

Why write a manual? Quite simply that all of the existing documentation is inadequate. Despite numerous one page articles, readme's, changelogs, random notes, and partial tutorials, RetroForth suffers from a lack of usable documentation. This is my attempt to change that. How long will this manual be when finished? That's hard to say. Considering the amount of material it will cover, probably longer than any other documentation I've written (~100 pages?). Keeping it up to date will take considerable time, so I'll be uploading it to the Wiki in the near future.

When finished this will cover:
  1) Background Information
    A) What is RetroForth?
    B) History of RetroForth
  2) Installation and Usage Overview
    A) Downloading
    B) Setting up the sources
    C) Compiling
    D) Running
  3) Developing with RetroForth
    A) Using the Forth Shell
       1) Introduction to Forth programming
       2) Hints and Tricks
    B) Using the User Configuration System
       1) Writing Primitives
       2) Using Forth2asm
       3) Linking with C code and libraries
  4) RetroForth Internals
    A) Directory and File Structure
    B) Using the macros
    C) Adding Primitives
    D) Porting RetroForth
  5) Appendixes
    A) RetroForth Words
    B) Glossary of terms
    C) "The Design Philosophy of RETRO Native Forth"

What is RetroForth?

Quite simply, RetroForth is an open-source implementation of the Forth programming language. To be more specific, it is a framework for developing and distributing programs written in Forth.

Forth is a powerful language, but is difficult for most programmers to learn and use effectively. There are also many times when it is more practical to write and use code that is written in other languages. RetroForth makes this quite easy. Using the highly flexible and easy to learn macros, importing and using routines written in C or other popular languages is quite easy. In fact, we encourage this. Under Linux, the graphical display drivers are built over SVGALIB and SDL, showing how straightforward this process is.


A Brief History of RetroForth

In 1998, RetroForth began life as a simple operating system project. Tom Novelli had been seeking a way to make computer software simpler, and was in the process of writing his own language when he stumbled upon Forth. The first version of RetroForth was a crude 16-bit system that used the BIOS for everything. While it worked, it was slow and not really simple. To overcome the problems, Tom Novelli rewrote it in 1999 and released Retro 2 to the world.

In the second generation, RetroForth grew to become a bloated operating system with many features. Sadly it remained overly complex and very buggy. As time went on, Tom began work on a third generation of RetroForth.

The third generation of RetroForth was vastly different than the first two. For the first time, it was written totally in Forth and contained a usable assembler and meta-compiler. After extensive work, this was also abandoned due to difficulties in implementation.

Tom's final attempt yielded Retro4. In this rewrite, RetroForth returned to use of an assembly kernel, but also provided an easy means of adding Forth code to the system. After releasing Retro4b, Tom decided to retire RetroForth to work on a more usable operating system.

In 2002, Charles Childers decided to fork development of the now abandoned Retro4 code base. His early efforts made several small improvements to the system, and led to a change in control of the project. With the start of 2003, RetroForth 5.0 was released. As an extension of Retro4, it focused on usability and soon restored viability to the RetroForth project. Continued use revealed that it was beginning to become overly complex, so a new version began to be worked on.

Retro-NG was the start of the current implementation of RetroForth. It provided a smaller kernel in assembly language, and a usable Forth implementation on top of this kernel. When this was released to the public as RetroForth 6, a flurry of new development occurred. Thanks to Tom Novelli, RetroForth gained the ability to run under Linux as console application. A short time later, an SVGALIB version was released. Then came support for use of SDL as a display target and RetroForth became more usable than ever before.

Today development continues. Retro-NG is still being worked on and is forming the basis for a wide range of software solutions. Though it can still be used as an operating system, the emphasis is on providing a rich programming environment for traditional operating systems. In the future, we hope to release RetroForth on other operating systems, including Windows, BeOS, FreeBSD, and Syllable.



Obtaining and Installing RetroForth

Goto http://retro.tunes.org/pub and download the most recent release of RetroForth. The filenames show the release and revision numbers to help in locating the most recent version.

Older revisions (6.11 and earlier) used a filename of retro6-buildX.tar.gz, where X was the revision. Starting in Release 6.12, the filenames take the form of rf-6_X.tar.gz where X is the revision number.

Once you've downloaded the source package, you'll have to extract it. Goto a shell and type:
   gunzip rf-6_X.tar.gz
   tar xf rf-6_X.tar
Be sure to replace rf-6_X.tar.gz with the name of the file you downloaded. Once this is done, you will have a directory named 'retro6' or 'retroforth' containing the source tree for RetroForth.


Compiling and Running RetroForth

This is also easy. Enter the shell again, and goto the retroforth/source directory. Type:
  . build
and wait while the binaries are built. Once this process is complete, you will have a few binaries in the images/ subdirectory. A few of these (fat12, rawfloppy, and retro.com) are for running RetroForth natively or under DOS. Under Linux you will need to use 'rf', 'rf-vga', or 'rf-sdl' to run RetroForth.

The 'rf' binary will almost always work, though it lacks many of the features in the other binaries. It is a console application, and directly communicates with the kernel.

The other two are quite similar (only a few driver-related differences). 'rf-vga' uses SVGALIB to render its graphics, and may require you to have root privileges to run. The other binary (rf-sdl) uses SDL and runs under the X Window System. If either library is missing the corresponding binary will not run or compile. 


Customising RetroForth

Most uses of RetroForth will center on developing standalone (i.e. not using the interactive Forth shell) applications. To make this simpler, Release 6.11 and higher added two files in the source/user directory. These files (user.f and user.asm) are all you need to change to generate your own applications. As an example, let's create the classic "Hello World!" example in RetroForth.

Edit user.f to contain the following code:

" Hello, World!" type cr bye

And then recompile and run one of the binaries. As you can see, this application displays "Hello, World!", then exits. Using user.asm, you can insert loops, conditionals, and add your own primitives. By combining the two, any application can be built around the RetroForth core.



Glossary of Words
clear pop push stack: string: " array cells cell+ allot align pad -- ++ +! on off */mod */ /mod - neg 2drop 2dup tuck nip over -rot 3, 2, 1, , here octal decimal hex pad-area false true ( fill abs mod / * not rot swap drop ]code code[ dup db, offset asmbase variable constant words word type ! s rot . + @ cmove call, bytes : ] create x, source base d h key emit cr bye bye

call,
  Calls an assembly language subroutine
  ( a -- )
@
  Reads a value stored at a memory location
  ( a -- n )
!
  Writes a value to a memory location
  ( n a -- )
db,
  Stores a byte into a memory location
  ( b -- )
bytes
  Stores a number of bytes into memory using db,
  ( n -- )
code[
  Sets up the Retro Assembler for assembling code
  ( -- )
]code
  Switches back to plain Forth mode, and calls the assembled code
  ( -- )
asmbase
    Stores the starting address of all assembled words
offset
    Stores the next byte in an assembly definition
+
   Adds top two numbers on the stack
   ( n1 n2 -- n3 )
*
   Multiplies top two numbers on the stack
   ( n1 n2 -- n3 )
-
   Subtracts top two numbers on the stack
   ( n1 n2 -- n3 )
/
   Divides top two numbers on the stack
   ( n1 n2 -- n3 )
neg
   Changes the sign of a number
   ( n -- n )
hex
   Changes the numeric base to hexadecimal
   ( -- )
   Forth
decimal
   Changes the numeric base to decimal
   ( -- )
rot
   Places the bottom number on the stack onto the top.
   ( n1 n2 n3 -- n2 n3 n1 )
-rot
   Undoes a rot
   ( n2 n3 n1 -- n1 n2 n3 )
dup
   Duplicates the top number on the stack
   ( n -- n n )
drop
   Drops the top number off the stack
   ( n -- )
swap
   Switches the top two numbers on the stack
   ( n1 n2 -- n2 n1 )
over
   Copies the number right below the top of the stack to the top
   ( n1 n2 -- n1 n2 n1 )
nip
   Drops the number right below the top of the stack
   ( n1 n2 n3 -- n1 n3 )
tuck
   Switches the top of stack with the number below it, then does an over
   ( n1 n2 -- n2 n1 n2 )
s
   Accepts a sequence of characters (ending with ENTER key) from the
   keyboard and returns a counted string at a
   ( a -- a n )
word
   Parses a string for a character specified by the top of the stack.
   ( b -- a n )
   Primitive
"
   Create a counted string
   ( -- a n )
cr
   Goes down one line on the screen
   ( -- )
type
   Displays a counted string
   ( a n -- )
.
   Displays a number
   ( n -- )
key
   Reads a key press from the keyboard and stores its value on the stack
   ( -- n )
emit
   Displays the ASCII symbol for the number on the TOS
   ( n -- )
clear
   Clears the screen
   ( -- )
here
   Returns the memory address of the end of the code space
   ( -- a )
:
   Creates a new word
   ( -- )
   Usage ->   : NAME words to execute ;
variable
   Creates a new variable
   ( -- )
   Usage ->   INITAL_VALUE variable NAME
constant
   Creates a new constant
   ( n -- )
   Usage ->   VALUE constant NAME
create
   Creates a new named value. By default this is a variable.
   ( -- )
does>
   ( -- )
[
   ( -- )
]
   ( -- )
at
   Moves the cursor position
   ( x y -- )
tc
   ( -- )
blit
   Copy a rectangle to X Y
   ( width height x y -- )
hline
   Draws a horizontal line with length N
   ( n -- )
vline
   Draws a vertical length with height N
   ( n -- )
(
   Allows use of comments
   ( -- )
true
   Returns -1, the traditional value of TRUE
   ( -- n )
false
   Returns 0, the traditional value of FALSE
   ( -- n )
on
   Turns a variable on
   ( a -- )
off
   Turns a variable off
   ( a -- )
base
   Stores the current numeric base
   ( -- a)
color
   ( -- )
bgColor
   ( -- )
xy
   Stores the current screen coordinates
   ( -- a)
source
   Stores the current input source
   ( -- a)
d
h






Use and Misuse of RetroForth
----------------------------
RetroForth is public domain. All of the official source code and/or binaries are completely free. This is true "free software" and "open-source". You are welcome (and encouraged!) to modify the source and distribute your changes. In fact, to do anything meaningful with RetroForth, you will have to modify at least a few files.

While RetroForth is public domain, we do encourage all users to share their extensions, bug fixes, and sample code with the rest of the RetroForth community. If you release a modified version, we would like to receive credit for our work. Use of the RetroForth name for modified versions requires permission from the current maintainer(s)/developer(s).

Commercial users are also encouraged to give credit to the authors of RetroForth. While no person or company is required to, a mention in the documentation would be great!

In general you can't misuse RetroForth. Please be aware that we offer no license or warranty for use of RetroForth! By installing and/or using RetroForth (or derivatives of it), you are taking full responsibility for damages to your computer(s). You've been warned...


Conclusion

I hope you enjoy using RetroForth!
