README file for kforth for Macintosh OS X ppc

Copyright (c) 1999--2004, 2006 Creative Consulting for Research
and Education

Last Revised: 06-14-2006

GENERAL
-------

kforth for Mac OS X ppc is provided under the terms of the GNU
General Public License.  The license terms for this software are
explained at our website:

http://ccreweb.org

New releases of this software will be posted at the website, as
they become available. Online documentation is also available at
the website. Further information may be obtained by sending
e-mail to:

krishna.myneni@ccreweb.org

The ppc virtual machine code is also licensed under the terms of
the GNU Lesser General Public Licens.

INSTALLATION 
------------

The OS X ppc version kforth is distributed as a compressed tar
(Unix Tape Archive) file with the name:

	kforth-ppc-osx-x.y.z.tar.gz

where x.y.z is the version number, e.g. 1.2.5.

This file contains the source code files and a Makefile for
building the executable.  The GNU C/C++ development files
(version 3.2 or later) are required to be installed on your
system.  In addition, the 'readline' and 'ncurses' libraries
must be available.

Follow these steps to build and install kforth on your system:


1. Create a directory for the kforth source files, typically
   in your home directory, e.g.

	mkdir ~/kforth

2. Move the kforth archive file into this directory:

	mv kforth-pclinux-x.y.z.tar.gz ~/kforth

3. Change to the ~/kforth directory and extract the
   files:

	cd ~/kforth
	tar -zxvf kforth-pclinux-x.y.z.tar.gz

   After this step, a subdirectory will be created with the
   name kforth-x.y.z. This directory will contain all of the kforth
   source files, the Makefile(s), and this README file.

4. Change to the kforth-x.y.z directory:

       cd kforth-x.y.z

5. Build the kforth executable. There are several options for
   building kforth, but the simplest is to type:

	make

   All of the source files will be compiled/assembled and two
   executable files, named "kforth" and "kforth-fast", will be 
   generated. 

6. At this point you should be able to run the executables from
   your ~/kforth/kforth-x.y.z directory. If you wish to make 
   kforth available to all users or to place the programs in the
   default search path, move the executables to a suitable directory.
   Typically you must have root access to do this. Login as
   root or superuser:

        su

   Next, move the executables to an appropriate directory
   (/usr/local/bin/ is recommended):
	
	mv kforth /usr/local/bin/
	mv kforth-fast /usr/local/bin/

   Any user should then be able to execute kforth or kforth-fast. 
   Return to normal user mode (exit from superuser mode).

7. Sample source code files, with the extension ".4th", are
   included in the archive file. These files are intended to
   serve as programming examples for kforth.

8. You may specify a default directory in which kforth
   will search for .4th files not found in the current
   directory. The environment variable KFORTH_DIR must
   be set to this directory. For example, under the BASH
   shell, if you want the default directory to be 
   your ~/kforth/kforth-x.y.z directory, add the following 
   lines to your .bash_profile file:

	KFORTH_DIR=~/kforth/kforth-x.y.z
	export KFORTH_DIR

9. The file kforth.xpm may be used to create a desktop icon
   for kforth under X Windows. For example, if you are using
   the KDE environment, copy kforth.xpm to the /usr/share/icons
   directory.

Contact CCRE via email at the email address given above if you 
have problems installing the software on your system.