Solo Forth README

Description of the page content

Contents of the README file included in Solo Forth

Tags:

README file

Description

Solo Forth is a Forth system for the ZX Spectrum 128 and compatible computers, with disk drives and +3DOS, G+DOS, or TR-DOS.

Solo Forth cannot run on the original ZX Spectrum 48, but could be used to develop programs for it.

Solo Forth can be used as a stand-alone Forth system (either in an emulator or on the real computer), or as part of a cross-development environment in a GNU/Linux operating system (in theory, other type of operating systems could be used as well).

Main features

  • Fast DTC (Direct Threaded Code) implementation.

  • A kernel as small as possible.

  • Name space in banked memory, separated from code and data space.

  • Easy access to banked memory.

  • Big library of useful source code.

  • Modular DOS support.

  • Fully documented source code.

  • Detailed documentation.

  • Conform to the Forth standard (not fully tested yet).

Minimum requirements

  • 128 KiB RAM.

  • One double-sided 80-track disk drive (two or three recommended, depending on the DOS).

Motivation, history and current status

The motivation behind Solo Forth is double:

  1. I wanted to program the ZX Spectrum with a modern Forth system: In 2015, my detailed disassembly of ZX Spectrum’s Abersoft Forth, a popular tape-based implementation of fig-Forth ported to several 8-bit home computers in the 1980’s (and the Forth system I started learning Forth with in 1984), helped me understand the inner working of the fig-Forth model, including its by-design limitations, compared to modern Forths, and discover some bugs of the ZX Spectrum port. At the same time I wrote the Afera library in order to make Abersoft Forth more stable, powerful and comfortable for cross development. The objective was reached but, after a certain point, further improvements weren’t feasible without making radical changes in the system. The need for a new Forth system arised: a Forth designed from the start to use disk drives and banked memory, and useful for cross-development.

  2. Nobody had written such a Forth system before: In 2015 there was no disk-based Forth for the ZX Spectrum platform, and the only Forth written for ZX Spectrum 128 (the first model with banked memory) was Lennart Benschop’s Forth-83 (1988). But despite being more powerful than fig-Forth, it is still tape-based and keeps the block sources in a RAM disk. Besides, the system is built by metacompilation, what makes it difficult to adapt to disk drives.

The development of Solo Forth started on 2015-05-30, from the disassembled code of Abersoft Forth. Some ideas and code were reused also from the Afera library and from a previous abandoned project called DZX-Forth (a port of CP/M DX-Forth to ZX Spectrum +3e).

On 2016-03-13 a Git repository was created from the development backups, in order to preserve the evolution of the code from the start, and uploaded to GitHub. On 2020-12-05 the Git repository was converted to Fossil, keeping GitHub as a mirror. On 2023-04-06 the repository was converted to Mercurial, enabling a better interaction with GitHub. On 2023-09-12 the Mercurial repository was published on Sourcehut, keeping GitHub as a mirror.

Solo Forth is very stable, and it’s being used to develop two projects in Forth: Nuclear Waste Invaders and Black Flag.

Platforms

Table 1. Supported platforms
Computer Disk interface DOS

Pentagon 128

TR-DOS

Pentagon 512

TR-DOS

Pentagon 1024

TR-DOS

Scorpion ZS 256

TR-DOS

ZX Spectrum 128

Beta 128

TR-DOS

ZX Spectrum 128

Plus D

G+DOS

ZX Spectrum +2

Beta 128

TR-DOS

ZX Spectrum +2

Plus D

G+DOS

ZX Spectrum +2A

(External disk drive)

+3DOS

ZX Spectrum +2B

(External disk drive)

+3DOS

ZX Spectrum +3

+3DOS

ZX Spectrum +3e

+3DOS

Project directories

Directory Subdirectory Description

backgrounds

Version background images

bin

ZX Spectrum binary files for disk 0

bin

addons

Code loaded from disk, not assembled in the library yet

bin

dos

DOS files

bin

fonts

Fonts for the supported screen modes

disks

Disk images

disks

gplusdos

G+DOS disk images

disks

plus3dos

+3DOS disk images

disks

trdos

TR-DOS disk images

doc

Manuals in DocBook, EPUB, HTML and PDF

make

Files used by make to build the system

screenshots

Version screenshots

src

Sources

src

addons

Code to be loaded from disk. Not used yet.

src

doc

Files used to build the documentation

src

inc

Z80 symbols

src

lib

Library

src

loader

BASIC loader for disk 0

tmp

Temporary files created by make

tools

Development and user tools

vim

Vim files

vim

ftplugin

Filetype plugin

vim

syntax

Syntax highlighting

Disks

The <disks> directory of the directory tree contains the disk images:

disks/*/disk_0_boot.*
disks/*/disk_1*_library.*
disks/*/disk_2_programs.*
disks/*/disk_3_workbench.*

The subdirectory and the filename extension of every DOS are the following:

Table 2. DOS subdirectories and disk image filename extensions
DOS Subdirectory Filename extension

+3DOS

plus3dos

dsk

G+DOS

gplusdos

mgt

TR-DOS

trdos

trd

How to run

In +3DOS

On ZX Spectrum +3/+3e

  1. Run a ZX Spectrum emulator and select a ZX Spectrum +3 (or ZX Spectrum +3e). Make sure its disk drives are configured as double-sided and 80-track in the emulator.

  2. “Insert” the disk image file <disks/plus3dos/disk_0_boot.dsk> as disk 'A'.

  3. Choose “Loader” from the computer start menu. Solo Forth will be loaded from disk.

In G+DOS

On ZX Spectrum 128/+2 with the Plus D interface

  1. Run a ZX Spectrum emulator and select a ZX Spectrum 128 (or ZX Spectrum +2) with the Plus D disk interface. Make sure its disk drives are configured as double-sided and 80-track in the emulator.

  2. “Insert” the disk image file <disks/gplusdos/disk_0_boot.mgt> as disk 1 of the Plus D disk interface.

  3. Choose "128 BASIC" from the computer start menu.

  4. Type run in BASIC. G+DOS will be loaded from disk, and Solo Forth as well.

In TR-DOS

Important

The TR-DOS version of Solo Forth uses numbers as disk drive identifiers (the same numbers TR-DOS uses internally) instead of the letters used by the TR-DOS BASIC interface:

Table 3. TR-DOS disk drive identifiers
Drive In TR-DOS In Solo Forth

1st

A

0

2nd

B

1

3rd

C

2

4th

D

3

On Pentagon 128

  1. Run a ZX Spectrum emulator and select a Pentagon 128. Make sure its disk drives are configured as double-sided and 80-track in the emulator.

  2. “Insert” the disk image file <disks/trdos/disk_0_boot.128.trd> as disk 'A'.

  3. Choose “TR-DOS” from the computer start menu. This will enter the TR-DOS command line[1].

  4. Press the 'R' key to get the RUN command and press the Enter key. Solo Forth will be loaded from disk.

On Pentagon 512

  1. Run a ZX Spectrum emulator and select a Pentagon 512. Make sure its disk drives are configured as double-sided and 80-track in the emulator.

  2. “Insert” the disk image file <disks/trdos/disk_0_boot.pentagon_512.trd> as disk 'A'.

  3. Choose "128k menu"[2] from the computer start menu (the reset service menu). This will enter a ZX Spectrum 128 style menu. Choose “TR-DOS”. This will enter the TR-DOS command line[1].

  4. Press the 'R' key to get the RUN command and press the Enter key. Solo Forth will be loaded from disk.

On Pentagon 1024

  1. Run a ZX Spectrum emulator and select a Pentagon 1024. Make sure its disk drives are configured as double-sided and 80-track in the emulator.

  2. “Insert” the disk image file <disks/trdos/disk_0_boot.pentagon_1024.trd> as disk 'A'.

  3. Choose "128k menu"[2] from the computer start menu (the reset service menu). This will enter a ZX Spectrum 128 style menu. Choose “TR-DOS”. This will enter the TR-DOS command line[1].

  4. Press the 'R' key to get the RUN command and press the Enter key. Solo Forth will be loaded from disk.

On Scorpion ZS 256

  1. Run a ZX Spectrum emulator and select a Scorpion ZS 256. Make sure its disk drives are configured as double-sided and 80-track in the emulator.

  2. “Insert” the disk image file <disks/trdos/disk_0_boot.scorpion_zs_256.trd> as disk 'A'.

  3. Choose "128 TR-DOS" from the computer start menu. Solo Forth will be loaded from disk.

On ZX Spectrum 128/+2 with the Beta 128 interface

  1. Run a ZX Spectrum emulator and select a ZX Spectrum 128 (or ZX Spectrum +2) with the Beta 128 interface. Make sure its disk drives are configured as double-sided and 80-track in the emulator.

  2. “Insert” the disk image file <disks/trdos/disk_0_boot.128.trd> as disk A of the Beta 128 interface.

  3. Choose "128 BASIC" from the computer start menu.

  4. Type randomize usr 15616 in BASIC (or just run usr15616 to save seven keystrokes). This will enter the TR-DOS command line[1].

  5. Press the 'R' key to get the RUN command and press the Enter key. Solo Forth will be loaded from disk.

How to use the library

In +3DOS

  1. Run Solo Forth.

  2. “Insert” the file <disks/plus3dos/disk_1_library.dsk> as disk B. 'b' set-drive throw to make drive 'B' the current one.

  3. Type 1 load to load block 1 from the library disk. By convention, block 0 cannot be loaded (it is used for comments), and block 1 is used as a loader. In Solo Forth, block 1 contains 2 load, in order to load the need tool from block 2.

  4. Type need name, were “name” is the name of the word or tool you want to load from the library.

In G+DOS

  1. Run Solo Forth.

  2. “Insert” the file <disks/gplusdos/disk_1_library.mgt> as disk 2 of the Plus D disk interface. Type 2 set-drive throw to make drive 2 the current one.

  3. Type 1 load to load block 1 from the library disk. By convention, block 0 cannot be loaded (it is used for comments), and block 1 is used as a loader. In Solo Forth, block 1 contains 2 load, in order to load the need tool from block 2.

  4. Type need name, were “name” is the name of the word or tool you want to load from the library.

In TR-DOS

  1. Run Solo Forth.

  2. “Insert” the file <disks/trdos/disk_1a_library.trd> into the first disk drive (called A in TR-DOS and 0 in Solo Forth), and the file <disks/trdos/disk_1b_library.trd> into the second disk drive (called B in TR-DOS and 1 in Solo Forth).

    Notice that the library is split into two disks because the maximun capacity of a TR-DOS disk is only 640 KiB.

    Also remember in Solo Forth the TR-DOS disk drive identifiers are numbers 0..3 instead of letters A..D.

  3. Type 1 load to load block 1 from the first library disk. By convention, block 0 cannot be loaded (it is used for comments), and block 1 is used as a loader. In Solo Forth, block 1 contains 2 load, in order to load the need tool from block 2.

  4. Type need 2-block-drives to load and execute the word 2-block-drives from the library, setting the first two drives as block drives in their normal order.

  5. Type need name, were “name” is the name of the word or tool you want to load from the library.

Documentation

The <doc> directory contains one version of the manual for every supported DOS, EPUB, HTML and PDF formats. The manuals are built automatically from the sources and other files. At the moment they contain a description of the Forth system, the basic information required to use it and a complete glossary with cross references.

1. The TR-DOS command line uses keyboard tokens, like the ZX Spectrum 48, but commands typed in 'L' cursor mode will be recognized as well, as on the ZX Spectrum 128 editor. In order to get the 'L' cursor mode you can type a quote (Symbol Shift + 'P') or press 'E' to get keyword REM. When the DOS command is typed in full, the quote or the REM must be removed from the start of the line before pressing 'Enter'.
2. In theory, choosing option “TR-DOS” from the system service menu should work. But it seems it depends on a specific version of TR-DOS. This alternative method is longer, but it works with the TR-DOS 5.03 ROM.