The Forth Foundation Library (FFL)
                 ==================================

The Forth Foundation Library is a general purpose forth library. It gives you a collection of words written in (ANS) Forth, in areas such as data types, collections, development support, interfaces and compound modules. The library is developed with gforth.

At the moment the library is still under development. The FFL library, the example and test files are licensed under the GNU GPL.

Installation, Configuration And Testing

gforth (Debian/Ubuntu)

Step 1: install the library with the Debian package a. Download and install the ffl-gforth_x.y.z-1_all.deb package b. Start gforth c. Enter: include ffl/frc.fs d. If gforth doesn't report an error, the library is correctly installed.

Step 2: Configuration of the library With the Debian package no further configuration is necessary.

Step 3: Test the library The test scripts are installed in the /usr/share/ffl/x.y.z/test directory. Due to ownership of those files (root), it is not possible to run the tests directly in this directory, so .. a. Create a temporary directory. For example: mkdir ~/ffl-test b. Copy the test scripts to the temporary directory: cp /usr/share/ffl/x.y.z/test/* ~/ffl-test c. Change the current directory to the temporary directory: cd ~/ffl-test d. Enter: gforth ffl_test.fs -ab -c TEST --verbose --file=FILE input (the command line arguments are for test purposes and have no real meaning, enter them in the correct case) e. The test script will tell you which modules are tested and if there were any errors. If you see: 'Forth Foundation Modules Test: 0 errors in xxxx tests.' then all went well. f. Don't forget to cleanup the temporary directory.

Some notes for the Debian package: a. The library is installed in /usr/share/gforth/site-forth/ffl b. The test scripts are installed in /usr/share/ffl/x.y.z/test c. The examples are installed in /usr/share/ffl/x.y.z/examples d. The documentation is installed in /usr/share/doc/ffl

Due to file ownership reasons the test scripts and examples can not be started directly in the install directories, but must be copied to temporary directories under your own account.

Tested with gforth-0.7.0.

gforth (non-windows)

Gforth uses a search path to find sources. If you install the ffl library in this search path, gforth can find the library.

Step 1: install the library in the search path: a. Start gforth b. Enter: fpath .fpath c. Gforth will show all the directories where sources are searched d. Select a search directory that ends with 'site-forth' and exists e. Copy the 'ffl' directory (and its contents) from the package to the selected directory f. Start gforth again g. Enter: include ffl/frc.fs h. If gforth doesn't report an error, the library is correctly installed, else repeat the steps, but select a different directory

Step 2: Configuration of the library For gforth no futher configuration is necessary.

Step 3: Test the library a. Change the current directory to the 'test' directory in the package b. Enter: gforth ffl_test.fs -ab -c TEST --verbose --file=FILE input (the command line arguments are for test purposes and have no real meaning, enter them in the correct case) c. The test script will tell you which modules are tested and if there were any errors. If you see: 'Forth Foundation Modules Test: 0 errors in xxxx tests.' then all went well.

Tested with gforth-0.7.0.

gforth (windows)

Gforth uses a search path to find sources. If you install the ffl library in this search path, gforth can find the library.

Step 1: Install the library in the search path: a. Start gforth b. Enter fpath .fpath c. Gforth will show all the directories where sources are searched d. If all shown directories start with '/usr', then gforths search path is incorrect, else continue with j. e. Determine where gforth is installed, this will normally be '<drive>:\Program Files\gforth' f. Add the environment variable: 'GFORTHPATH' with the value '\Program Files\gforth:.' (Environment variables can be added by: My Computer - Properties - Advanced - Environment Variables) g. Start gforth again h. Enter fpath .fpath i. Gforth should show '\Program Files\gforth' and '.' j. Copy the 'ffl' directory (and its contents) from the package to a search directory (except '.'). k. Start gforth again l. Enter: include ffl/frc.fs m. If gforth doesn't report an error, the library is correctly installed, else repeat the steps but select a different directory

Step 2: Configuration of the library For windows the 'end-of-line' word should be changed in the ffl/config.fs file, so that it will return cr-lf. See the configuration chapter for more info about the configuration items.

Step 3: Test the library a. Start cmd b. Change the current directory to the 'test' directory in the package c. Enter: gforth ffl_test.fs -ab -c TEST --verbose --file=FILE input (the command line arguments are for test purposes and have no real meaning, enter them in the correct case) d. The test script will tell you which modules are tested and if there were any errors. If you see: 'Forth Foundation Modules Test: 0 errors in xxxx tests.' then all went well.

Tested with gforth-0.7.0.

bigforth

Bigforth uses a search path to find sources. If you install the ffl library in this search path, bigforth can always find the library.

Step 1: Install the library in the search path: a. Start bigforth b. Enter: path c. Bigforth will show all the directories where sources are searched, separated by a ';' d. Select one of the search directories that exists, but not the '.' directory e. Copy the 'ffl' directory (and its contents) from the package to the selected directory f. Copy from the 'engines/bigforth' directory in the package the files 'config.fs' and 'make.fs' to the 'ffl' directory in the selected directory, resulting in 'ffl/config.fs' and 'ffl/make.fs'. g. Start bigforth again h. Enter: include ffl/frc.fs i. If bigforth doesn't report an error, (exists warnings are okee), the library is correctly installed, else repeat the steps, but select a different directory

Step 2: Configuration of the library: For bigforth the 'end-of-line' configuration in the ffl/config.fs file is set for Unix/Linux. If you install bigforth for an different OS, you should change the 'end-of-line' word. See the configuration chapter for more info about the configuration items.

Step 3: Test the library: a. Change the current directory to the 'test' directory in the package b. Enter: bigforth ffl_test.fs c. The test script will tell you which modules are tested and if there were any errors. If bigforth only reports errors for the fwt module, then all went well. Bigforth reports errors for the fwt module, due to missing alignment code in this forth engine.

Tested with bigforth 2.3.1

pfe

PFE uses a search path to find sources. If you install the ffl library in this search path, pfe can find the library.

Step 1: Install the library in the search path: a. Start pfe b. Enter: .status c. After the item 'search path for source files' pfe lists the directories, separated by ':', that are used as search path. d. Select one of the search directories, but not the '.pfe' directory e. Copy the 'ffl' directory (and its contents) from the package to the selected directory f. Copy from the 'engines/pfe' directory in the package the files 'config.fs' and 'make.fs' to the 'ffl' directory in the selected directory, resulting in 'ffl/config.fs' and 'ffl/make.fs'. g. Start pfe again h. Enter: include ffl/frc.fs i. If pfe doesn't report an error, the library is correctly installed, else repeat the steps, with a different directory.

Step 2: Configuration of the library: For pfe the 'end-of-line' configuration in the ffl/config.fs file is set for Unix/Linux. If you install pfe for an different OS, you should change the 'end-of-line' word. See the configuration chapter for more info about the configuration items.

Step 3: Test the library: a. Change the current directory to the 'test' directory in the package b. Enter: pfe ffl_test.fs -ab -c TEST --verbose --file=FILE input (the command line arguments are for test purposes and have no real meaning, enter them in the correct case) c. The test script will tell you which modules are tested and if there were any errors. If you see: 'Forth Foundation Modules Test: 0 errors in xxxx tests.' then all went well.

Tested with pfe 0.33.70

Win32Forth

Win32Forth uses a search path to find sources. If you install the ffl library in this search path, Win32Forth can find the library.

Step 1: Install the library in the search path: a. Start Win32Forth b. Enter: .fpath c. This word shows first the 'Base paths' and after that the 'Search paths'. d. First select one directory of the 'base paths' and combine that with one of the 'search paths'. e. For example if you select 'c:\program files\win32forth' as base path and 'SRC\LIB' as 'search path', you should copy the 'ffl' directory (and its contents) from the package to the directory 'c:\program files\win32forth'. f. Copy from the 'engines/Win32Forth' directory in the package the files 'config.fs' and 'make.fs' to the 'ffl' directory in the selected directory, resulting in 'ffl/config.fs' and 'ffl/make.fs'. g. Start Win32Forth again h. Enter: include ffl/frc.fs i. If Win32Forth doesn't report an error (warnings are okee), the library is co