README

WHAT IS FINA?
=============

FINA (FINA Is Not ANS) is a small direct-threaded Forth
compiler/interpreter. Should be easy to port and embed in other
applications. Tries to follow the ANS Forth standard. Currently
supports PowerPC and X86 (MIPS and ARM untested).


ROOTS
=====

FINA takes some inspiration from:
- hForth ( http://www.taygeta.com/hforth.html )
- Gforth ( http://www.gnu.org/software/gforth/ ).


BUILD REQUIREMENTS
==================

- GCC ( http://gcc.gnu.org ). Versions 2.x and 4.x seem to generate
  better code than 3.x. In some cases, 3.x might even generate wrong
  code.

- SCons ( http://scons.org ). This one requires a Python installation.


BUILDING
========

Typing the following will build and install under a directory called "inst":

$ scons

To start the interpreter:

$ inst/bin/fina

To pass some regression tests, build with:

$ scons check=1

To perform some benchmarks, build with:

$ scons bench=1

To compile a call profiling version (for using prof.fs):

$ scons profile=1

To build a slow version with a minimal set of primitives:

$ scons moreprims=0

To avoid building the memory allocation words (ALLOCATE/FREE/RESIZE):

$ scons allocate=0

To compile a i386 version when the default compiler is 64 bits:

$ scons arch=i386

To force a x64 build when the architecture is reported as i386:

$ scons arch=x64

To clean the built files (~= make clean):

$ scons -c


INSTALLATION
============

To install, just build passing a prefix argument:

$ scons prefix=/tmp/fina


HELP
====

To read the documentation for a word, type:

help <word>


STATUS
======

You can get a report on implemented/missing words running:

$ inst/bin/fina test/checkans.fs


INTERNALS
=========

FINA doesn't use an image file. The image is contained in the
executable. That's the reason for the big size of the binary, it will
be as big as your desired dictionary size. This isn't as bad as it
might sound, since you can compress the executable with gzexe.
Compiling FINA with a dictionary size of 16 Mb will result in an
executable of ~16800000 bytes, but the stripped executable compressed
with gzexe will only take ~41000 bytes.

The default dictionary size is set to 64K cells. This and several other
values can be tweaked in meta/tconfig.fs

Wordlists have the following structure:

first-word-nfa|next-wordlist

NFA points to the LEN+FLAGS field of a word header. That is, the
following would inspect the first NFA in FORTH-WORDLIST

forth-wordlist @ 40 dump

Word headers have the following structure:

next-nfa|len+flags|name|(padding)|(body)

So, you can inspect the NFA of the word defined before DUP as follows:

' dup xt>name cell- @ 40 dump


THANKS
======

Thanks to the authors of hForth and Gforth for building those great
pieces of software.