VNPForth Forth compiler and runtime, version 1.4
------------------------------------------------


Introduction
------------
VNPForth implements a subset of ANS Forth, though enough of one to pass most
of the 1993 Johns Hopkins University / Applied Physics Laboratory tests for
core ANS Forth words.

Unlike most Forth systems, VNPForth has no word dictionary.  Instead, it
compiles to modular object (.o) files, just like C and C++ programs, and is
then linked into a suitable runtime in the same way as C programs too.
Because they use the same object file format as standard C, VNPForth modules
can call, and be called by, C and C++ modules.

The result of compiling VNPForth is a standalone executable program, requiring
no special runtime on the target system.  In the case of statically linked
programs, the binaries are orders of magnitude smaller than their C equivalent
would be, mostly due to the lack of any libc requirement.  Such small programs
might be useful items to tuck into a recovery floppy disk, or for use on
systems where memory and storage are limited.

VNPForth is very non-portable.  It contains assembly language code, written
with the GNU assembler in mind, that will run only on IA32 (and perhaps on
IA64) CPUs -- i386, i486, Pentium, and similar.  It also makes specific system
calls directly into the kernel, bypassing libc, so will not run on operating
systems other than Linux.  VNPForth requires at least a 2.2 or 2.4 Linux
kernel.


Quick start guide
-----------------
Here is a Forth version of the ubiquitous hello-world program:

    ." Hello from VNPForth" CR 0 DROP

To compile, link, and run this program, first save it in a file hello.ft:

    $ cat <<EOF >hello.ft
    ." Hello from VNPForth" CR 0 DROP
    EOF

Now compile and link the program to an executable 'hello'.  Assuming you have
installed the runtime library and forthrt.o module in /usr/local/lib, and the
forthc compiler is on your $PATH, the commands are:

    $ forthc hello.ft
    $ ld -static -o hello hello.o -L/usr/local/lib -lforth \
            /usr/local/lib/forthrt1.o

You should now be able to run the program:

    $ ./hello
    Hello from VNPForth

Unlike the same thing written in 'C', when statically linked this binary is
still extremely small, especially if you remove debugging information from it
(by default, libforth includes debugging data):

    $ strip ./hello

Compare this with the same small program written in 'C', and compiled into a
static 'chello' binary:

    $ cat <<EOF >chello.c
    main() { printf ("Hello from C\n"); }
    EOF
    $ cc -static -o chello chello.c
    $ strip chello


About the VNPForth source
-------------------------
Because VNPForth is not portable, and works only on IA32 Linux systems, there
is no configure script associated with the source.  Your system will need to
have a reasonably modern C++ compiler installed in order to build the Forth
compiler, and also Flex and Bison.

VNPForth will not port to other platforms without a considerable amount of
effort.  In particular, it makes direct system calls to the kernel, bypassing
libc, and so requires a Linux 2.2, 2.4, or later kernel on the system.  The
compiler generates IA32 assembler, and portions of the runtime library are
also written in IA32 assembler, so only Intel-based Linux systems will run
VNPForth.


Building VNPForth
-----------------
To build the compiler and Forth runtime libraries, type

    make all

in the directory where you unpacked the source code.  This will build the
Forth compiler, then use that compiler to build the Forth runtime and test and
example programs.  It will also run the compiler tests and the ANS Forth test
suite.  The Forth compiler is built as a static binary to minimize any possible
problems with VNPForth binary distributions and libc and libc++ DLLs.


Installing the library, man pages, and programs
-----------------------------------------------
Assuming the 'make all' succeeded, you can install the programs with

    make install

By default, this will install everything under /usr/local.  This will probably
need superuser privileges.

It is not necessary to install the programs in order to run them.  You should
be able to run any of them in the directories in which they built themselves.


Uninstalling VNPForth
---------------------
To uninstall the programs, use

    make uninstall

with the same user/permissions as you used for installing.  To clean out the
directory for a rebuild, use

    make clean


License
-------
VNPForth is distributed under the GNU GPL.  Please see the COPYING file for
details.


Acknowledgments
---------------
Thanks to Dirk Zoller (duz@roxi.rz.fht-mannheim.de).  I used his PFE package,
version 0.9.13, as a reference when I couldn't follow the ANSI standard, and
borrowed most of the core.ft test suite from PFE too.

Simon Baldwin,
simon_baldwin@yahoo.com
