		VNPForth v1.0 Forth compiler and runtime
		----------------------------------------

Introduction
------------
This program arose from a need to learn the finer details of the Intel
IA32 instruction set, coupled with a desire to implement a 'real'
compiler using Flex and Bison.

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.  VNPForth modules can call, and be called by, C and
C++ modules, since they use the same object file format as standard C.

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.

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...  It also makes
specific system calls directly into the kernel (bypassing libc), so
will not run on operating systems other than Linux, and more
specifically, Linux with at least a 2.2 or 2.4 kernel, without some
considerable modification.


Delivered tar files
-------------------
VNPForth comes in a single source files archive:

    vnpforth-N.N.tgz

where N.N represent the package release number.

This file contains all of the C source files for the compiler, and
the Forth source files for the runtime libraries.  It also contains a
handful of test and demonstration programs.


Building the source
-------------------
To build VNPForth, you will need to have Flex, Bison, make, and a
working C compiler installed on your system.

First, uncompress and untar the source into a suitable temporary
directory:

    $ gunzip -c <vnpforth-N.N.tgz | tar xvf -

Next, cd into the vnpforth-N.N subdirectory, and run the command

    $ make all

This will first build the VNPForth compiler, forthc, from its C, Flex,
and Bison source code, then go on to build the VNPForth runtime
libraries libforth.a, libforth.so, and the standalone object
forthrt1.o.

Assuming these items build, you can try

    $ make verify

This will compile and run the DPANS test suite, and the demonstration
programs.  At this point, you can use the compiler and runtime
libraries in the locations in which they built, in order to compile
and run Forth programs.  For example:

    $ cat <<EOF >>hello.ft
    ." Hello from VNPForth" CR 0 DROP
    EOF
    $ compiler/forthc hello.ft
    $ ld -static -o hello hello.o -Lruntime -lforth runtime/forthrt1.o
    $ ./hello
    Hello from VNPForth
    $


Installing the compiler and runtime
-----------------------------------
If you wish to install the compiler and runtime libraries as 'first
class' utilities, use the

    # make install

target.  You will need to be superuser for this command.  If you do
not have superuser privilege on your system, you will not be able to
run this command, since it writes to some of Linux's protected
directories.

Once installed, the compiler can be invoked directly, assuming /usr/bin
is in $PATH, and the ld command no longer needs to specify with -L the
location of libforth.  See the forthc and libforth man pages for more
compile and link examples, and also details on how to link VNPForth
modules with C and C++ modules in a single executable binary.

Use

    # make uninstall

to remove the compiler and runtime libraries from the system.


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


Version changes
---------------
Version 1.0:
	- First program release.


Simon Baldwin, simonb@sco.com
