README file for kForth for Linux

Copyright (c) 1999--2010 Creative Consulting for Research and Education
Last Revised: 05-01-2010

GENERAL
-------

kForth for Linux 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


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

The following packages are required to build and maintain kForth from
its source package, on a Linux system:

    binutils
    gcc
    gcc-c++
    glibc
    glibc-devel
    libstdc++-devel
    make
    readline
    readline-devel
    ncurses
    ncurses-devel
    patchutils

Some or all of these packages may already be installed on your Linux 
system, but if they are not, you should install them for your Linux
distribution. GNU C/C++ version 4.0 or later should be used.
 
kForth is distributed as a compressed tar (Unix Tape Archive) file
with the name:

	kforth-x86-linux-x.y.z.tar.gz

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

This file contains the source code files and a Makefile for building
the executable. 

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

1. Create a directory for the kforth source files, e.g.

	mkdir ~/kforth

2. Move the kforth archive file into this directory:

	mv kforth-x86-linux-x.y.z.tar.gz ~/kforth

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

	cd ~/kforth
	tar -zxvf kforth-x86-linux-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, example Forth files, the Makefile, this 
   README file, and the ChangeLog 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 kforth-x.y.z/examples/ subdirectory. These 
   files are intended to serve as programming examples for kforth, 
   in addition to providing useful libraries of Forth words and
   applications written in Forth. Within the examples/ subdirectory,
   you will find additional subdirectories containing different
   categories of Forth libraries or applications. These include:

	system-test/     A set of automated tests to validate the
                         Forth system against the Forth-94 standard

	fsl/             modules from the Forth Scientific Library,
                         including test code; also note the subdirs,
                         fsl/extras/ and fsl/demo/

	games/           console games written in Forth

	libs/            Forth interfaces to C and Fortran shared 
                         object libraries, such as X11.

	benchmarks/      simple benchmarks to compare the relative 
                         speed of Forth systems

   Important libraries in the examples/ subdirectory include,

	ans-words.4th   Forth-94 words provided in source form
	strings.4th     String handling library
	files.4th       Standard Forth words for file i/o
	ansi.4th        ANSI terminal control
	dump.4th	Forth DUMP utility
	syscalls.4th	Operating System calls

   An important application in examples/ is the 32-bit x86 assembler,

	asm-x86.4th

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 (or .profile on some
   systems):

	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.


Configuring the Emacs editor for Forth source files
---------------------------------------------------

The file gforth.el provides syntax highlighting and automatic indentation for
Forth source files. If you have installed Emacs on your system, you may 
configure Emacs for editing Forth source by doing the following:

1) Copy gforth.el to the appropriate directory on your system. For example, 
   on a SuSE Linux system, this directory is /usr/share/emacs/site-lisp/

2) Edit the Emacs customization file, .emacs, in your home directory to
   include the following lines:

   (autoload 'forth-mode "gforth.el")
   (setq auto-mode-alist (cons '("\\.fs\\'" . forth-mode) auto-mode-alist))
   (setq auto-mode-alist (cons '("\\.4th\\'" . forth-mode) auto-mode-alist))

The above changes will place Emacs in Forth mode when editing both .fs and
.4th files.

Another editor which offers Forth syntax highlighting is gedit, an
application for the GNOME desktop under Linux.

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




