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: krishna.myneni@ccreweb.org

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

where x.y.z is a version number such as 1.2.6. The source package unpacks to a directory of source files and a Makefile for building the executable(s). Windows users may also simply download the file kforth-pcwindows-x.y.z.zip if they only want to run kForth without building it from its source code.

Installation under Linux

The GNU C/C++ development packages (version 3.2 or later) are required to be installed on your system:

   gcc
   gcc-c++
   glibc
   glibc-devel
   libstdc++-devel
   make


These packages are typically installed by default for a Linux workstation configuration, but if they are not, you may install them manually from your Linux distribution.

In addition, the following packages are also required:

   readline
   readline-devel 
   ncurses
   ncurses-devel


On your Linux system, you may verify that these packages have been installed 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.

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-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), 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

Windows users may choose to install the binary distribution file only, or to build the kForth executables from source code. Instructions for both options are given below. Windows users should also 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.

Installing the kForth Binary Distribution for Windows

Follow these steps to install and use the binary distribution:

  1. Users of Windows 95, Windows ME, and Windows 98/SE have reported that kForth versions greater than 1.0.12 do not start properly from the Windows Command Prompt (also called the MS-DOS Prompt) under these systems. We strongly recommend that you use the Cygwin BASH shell to run kForth under these versions of Windows. This requires a minimal installation of Cygwin on your Windows system. From the Cygwin Home Page, click on the Install icon, which will download the Cygwin setup.exe program to your PC. Then run the setup.exe program. For a minimal installation, choose the Base + Default packages, when asked to select the packages. At the end of the installation, you will be prompted to create an icon for the Cygwin BASH shell on your desktop. Selecting this option will give you an icon on your Windows Desktop with which you can start the BASH command prompt window. Note that BASH provides Unix commands (cd pwd ls cp mv rm mkdir ...).

  2. Start the BASH shell. This will open the command prompt window, with the present directory set to /cygwin/home/username/, where username is your Windows user name.

  3. Make a directory for kForth:

    mkdir kforth


  4. Download the distribution file kforth-pcwindows-x.y.z.zip and unzip the contents into the kForth directory. The zip file contains the executables kforth.exe and kforth-fast.exe, the required dynamic link libraries cygwin1.dll, cygncursesx.dll, cygreadlinex.dll, and sample kForth programs.

  5. Execute kForth by typing ./kforth from within the kForth directory, using the BASH command window. To exit from kForth, type bye. To close the BASH command window, type exit from the BASH command prompt.


Building kForth From the Source Distribution for Windows

The Cygwin development tools must be installed on your Windows system in order to rebuild the executables starting from the source code. Follow these steps to build kForth from its source files on your Windows system:

  1. Install Cygwin on your system. Be sure to select the Development packages.

  2. Start the Cygwin BASH shell.

  3. Create a directory for the kForth source files, typically in the /usr/local/src directory, e.g.

    mkdir /usr/local/src/kforth


  4. Move the kForth archive file kforth-pcwindows-x.y.z.tar.gz into this directory:

    mv kforth-pcwindows-x.y.z.tar.gz /usr/local/src/kforth


  5. Change to the /usr/local/src/kforth directory and extract the files:

    	cd /usr/local/src/kforth
    	tar -zxvf kforth-pcwindows-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
    


  6. 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.

  7. 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.

  8. 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.

  9. 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 /usr/local/src/kforth, add the following lines to your .bash_profile file:

    	KFORTH_DIR=/usr/local/src/kforth
    	export KFORTH_DIR
    


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



    

Copyright © 1998--2004 Creative Consulting for Research and Education