Installation


kForth is provided under the terms of the GNU General Public License. New releases of this software will be posted at the CCRE website, as they become available. Online documentation is also available at the website. Difficulties with installation should be reported to: krishnamyneni@bellsouth.net

The kForth source package is distributed as compressed tar (Unix Tape Archive) files:

where x.y.z is the current version number,such as 1.3.2. The source package unpacks to a directory of source files and a Makefile for building the executable(s).

Installation under Linux

Required Packages

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


Note that some of the package names may be slightly different, depending on your Linux distribution. Some or all of these packages may already be installed on your Linux system, but if they are not, you should be able to install them manually for your Linux distribution. You may use your system's graphical package manager to check for installation of the required packages, or use a command line query. For example, if your Linux system is rpm-based, you may verify that these packages have been installed by using the rpm command in the following way:

rpm -q package

The above command will return the version number of the package if it has been installed. The version of GNU C/C++ should be 3.2 or higher. On a Debian package-based system, the following command line query may be used:

aptitude search package


While it may be tedious to determine the necessary package names and install any needed packages on your system, this is a one-time procedure which will enable your system to be used for building software from its source code, and for software development.

64-bit Linux Systems

kForth is always built as a 32-bit application, even on 64-bit systems. If you are building on a 64-bit system (x86_64), additional packages are needed to provide the 32-bit versions of the C/C++ libraries. The following additional package names are given for 64-bit Ubuntu Linux (7.10), and they may be different on other systems:


Build and Configuration

Assuming your Linux system has the required packages, follow these steps to unpack, build, and install kForth:

  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-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, the Makefile(s), as well as a README file with these same instructions.

  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 are included in the archive. These files have extension .4th. Users may copy the example programs to their own directories.

  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 ~/kforth/kforth-x.y.z, 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.


Installation under Windows

The Cygwin development tools must be installed on your Windows system in order to build or rebuild the executables from its source package. Windows users should note that kForth programs (text files having the extension .4th) must be stored in Unix text format rather than DOS text format. Many capable third-party text editors for Windows provide the option of saving text files in Unix text format. The Notepad editor does not have this option; however, one may use the WordPad program bundled with Windows to view and save text files in Unix text format. We recommend the Emacs editor for creating and editing .4th files. Follow these steps to build kForth from its source files on your Windows system:

  1. Install Cygwin on your system. The following packages, from the Devel category, are needed to build and maintain kForth:


    Note that the above list of packages is not installed by default in a Cygwin installation, so be sure to specifically select them from Devel when prompted by the Cygwin Setup program to select packages for installation. You may run the Setup program multiple times if you forget to select all of the packages.

  2. Download the kforth distribution file kforth-x86-cygwin-x.y.z.tar.gz into the user's cygwin home directory.

  3. Start the Cygwin BASH shell.

  4. Create a directory for the kForth source files, typically in the user's home directory, e.g.

    mkdir kforth


  5. Move the kForth archive file kforth-x86-cygwin-x.y.z.tar.gz into this directory:

    mv kforth-x86-cygwin-x.y.z.tar.gz kforth/


  6. Change to the kforth/ directory and extract the files:

    	cd kforth/
	tar -zxvf kforth-x86-cygwin-x.y.z.tar.gz


    After this step, a new directory called kforth-x.y.z will be created. This directory and its subdirectories contain all of the kforth source files, the Makefile(s), and a README file containing these instructions. Change to the source directory:

           cd kforth-x.y.z


  7. 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 the executable files, named kforth.exe and kforth-fast.exe, will be generated.

  8. Move the executables to the desired directory, typically into /usr/local/bin if you want to run them from any location within the bash shell.

  9. Sample source code files, with the extension .4th, are included in the archive file. These files are inteded to serve as programming examples for kForth.

  10. If you will be running kForth from the Cygwin BASH shell, 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 kforth/kforth-x.y.z, add the following lines to your .bash_profile file:

    	KFORTH_DIR=$HOME/kforth/kforth-x.y.z
	export KFORTH_DIR


  11. The file kforth.ico may be used to create a desktop icon for kforth under Windows.




Installation under Mac OS X

  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-ppc-osx-x.y.z.tar.gz ~/kforth


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

            cd ~/kforth
	tar -zxvf kforth-ppc-osx-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