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 modern standard Forth system under development for the ZX Spectrum 128 and compatible computers.

Solo Forth is focused on cross development of Forth programs for ZX Spectrum 128 using a ZX Spectrum emulator on a GNU/Linux operating system (in theory, other kind of operating system could be used as well).

Solo Forth is a complete Forth system. Therefore it can be used as a stand-alone Forth system on a ZX Spectrum emulator or the real computer, without any limitation, but that’s not its goal. Its goal is to be used as the last step of the development process, i.e. to compile and debug a Forth program on a ZX Spectrum emulator. The sources of the Forth program are edited on the host operating system and converted to Forth block disk images by tools that run on the host operating system.

Main features

  • Fast DTC (Direct Threaded Code) implementation.

  • A kernel as small as possible.

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

  • Transparent access to banked memory.

  • Big library of useful source code.

  • Modular DOS support.

  • Documented source code.

  • Detailed documentation.

History and current status

The development of Solo Forth started on 2015-05-30, from the disassembled code of Abersoft Forth, a tape-based fig-Forth 1.1 for ZX Spectrum 48.

The GitHub repository was created on 2016-03-13 from the development backups, in order to preserve the change history from the very beginning. Besides, there’s a development history until v0.12.0 (2016-12-31).

At the time of writing (2017-04-27) Solo Forth is under active development. It’s very stable, and it’s being used to develop two projects in Forth: Nuclear Waste Invaders and Black Flag.

Supported computers and disk operating systems

Solo Forth needs a ZX Spectrum or compatible computer with disk drives and at least 128 KiB of RAM. Therefore it can not run on the original ZX Spectrum 48, but in theory it could be used to develop Forth programs for it.

Table 1. Supported computers and disk operating systems
Computer Disk interface DOS

ZX Spectrum 128

Beta 128

TR-DOS

Plus D

G+DOS

ZX Spectrum +2

Beta 128

TR-DOS

Plus D

G+DOS

ZX Spectrum +3

+3DOS

ZX Spectrum +3e

+3DOS

Pentagon 128

TR-DOS

Pentagon 512

TR-DOS

Pentagon 1024

TR-DOS

Scorpion ZS 256

TR-DOS

Future targets

The DOS support in Solo Forth is modular, so in theory it would not be too difficult to support also other DOS in future versions. There are some ideas:

Porting the G+DOS version of Solo Forth to its close relatives GDOS, Beta DOS and Uni-DOS will require only minor changes, beside adding some library code to benefit from their specific features.

Supporting a more powerful and modern DOS like IDEDOS, ResiDOS, and esxDOS would require more effort, but would let Solo Forth use hard drives, flash cards, and a lot of memory, beside many other new features.

Porting the G+DOS version of Solo Forth to SAM Coupé (the powerful quite compatible cousin of ZX Spectrum) would not be a trivial task, because of the quite different OS and memory bank switching, but feasible.

Summary of the DOS support

G+DOS

G+DOS is the best supported DOS at the moment. Block disks are fully supported, but some file-management words are not implemented yet, especially the standard Forth words.

TR-DOS

TR-DOS is well supported. Block disks are fully supported, but many file-management words are not implemented yet, especially the standard Forth words.

+3DOS

Note
The +3DOS support does not work fine because of a recently introduced bug, which will be fixed in version 0.14.0.

The +3DOS support is still basic. Only the first drive can be used for block disks and most file-management words are not implemented yet, but standard Forth words are better supported than on G+DOS or TR-DOS.

Directory tree

The project directory has the following structure:

.
├── backgrounds       Version background images
├── bin               Binary files needed to build disk 0
│   ├── fonts         Fonts for the supported screen modes
│   ├── addons        Code that is loaded from disk
│   │                 because it's not assembled in the library yet
│   └── dos           DOS files
├── disks             Disk images
│   ├── gplusdos      G+DOS disk images
│   ├── plus3dos      +3DOS disk images
│   └── trdos         TR-DOS disk images
├── doc               Documentation
├── make              Files used by `make` to build the system
├── screenshots       Version screenshots
├── src               Sources
│   ├── inc           Z80 symbols files
│   ├── lib           Library
│   ├── loader        BASIC loader for disk 0
│   ├── addons        Code that is loaded from disk
│   └── doc           Files used to build the documentation
├── tmp               Temporary files created by `make`
├── tools             Development and user tools
└── vim               Vim files
    ├── ftplugin      Filetype plugin
    └── 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_games.*
disks/*/disk_3_workbench.*

The subdirectory and the filename extension depend on the DOS, as follows:

DOS Subdirectory Filename extension

G+DOS

gplusdos

mgt

TR-DOS

trdos

trd

+3DOS

plus3dos

dsk

  • Disk 0 is the boot disk. It contains the BASIC loader, the Solo Forth binary, some addons (i.e. compiled code that is not part of the library yet) and fonts for the supported screen modes. Two +3DOS boot disk images are included, with different sizes. Several TR-DOS disk images are included, for specific models of Pentagon and Scorpion computers (in a future version, one single disk will contain all the executables, and the right one will be selected automatically).

  • Disk 1 contains the sources of the library.

  • Disk 2 contains some little sample games, most of them under development.

  • Disk 3 contains tests and benchmarks used during the development.

Warning
Disks 1, 2 and 3 are Forth block disks: They contain the source Forth blocks directly on the disk sectors, without any file system. Therefore their contents can not be accessed with ordinary DOS commands.

How to run

On ZX Spectrum 128 (or ZX Spectrum +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.

  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.

On ZX Spectrum 128 (or ZX Spectrum +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.

  2. "Insert" the disk image file <disks/trdos/disk_0_boot.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 usr15360 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.

On ZX Spectrum +3 (or ZX Spectrum +3e)

  1. Run a ZX Spectrum emulator and select a ZX Spectrum +3 (or ZX Spectrum +3e).

  2. "Insert" the disk image file <disks/plus3dos/disk_0_boot.180.dsk> (or <disks/plus3dos/disk_0_boot.720.dsk>, depending on the capacity of the drive) as disk 'A'.

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

On Pentagon 128

  1. Run a ZX Spectrum emulator and select a Pentagon 128.

  2. "Insert" the disk image file <disks/trdos/disk_0_boot.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.

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

  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 Scorpion ZS 256

  1. Run a ZX Spectrum emulator and select a Scorpion ZS 256.

  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.

The library

Note
The library can not be used on +3DOS because of a recently introduced bug, which will be fixed in version 0.14.0.

The library disk contains the source code in Forth blocks, written directly on the disk sectors, without any filesystem. In order to use the library, follow these steps:

  1. Run Solo Forth.

  2. Insert the library disk:

    • On G+DOS: "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.

    • On TR-DOS: "Insert" the file <disks/trdos/disk_1_library.trd> as disk B of the Beta 128 interface. Type 1 set-drive throw to make drive 1[3] the current one.

    • On +3DOS: "Insert" the file <disks/plus3dos/disk_1_library.dsk> as disk A.

  3. Type 1 load to load block 1 from the library disk. By convention, block 0 can not 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 and related words from block 2.

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

Documentation

A HTML manual is included in the <doc> directory (actually, there are three versions of the manual, one for each supported DOS, but at the moment the only difference is the glossary). The manual is automatically built from the source files, which are almost fully documented, and from secondary files as well, like this README file, which in fact is an extract from the manual.

The manual is a work in progress. At the moment it contains only the basic information required to use the Forth system and an almost complete glossary with cross references.

The following sections are planned for a future version:

  • A reference guide by subject, e.g. graphics, sound, blocks, files, control flow structures, etc.

  • A description of the library modules.

Beside, in a next version of the manual, all Forth words will be links to the glossary entries. At the moment, only Forth words mentioned in the glossary are cross references.

Note
Glossary cross references to Forth words that contain a backslash, or that are included in code examples, are corrupted. This problem will be fixed in a future version.

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. Unfortunately, the only way to get 'L' cursor mode is typing a token first, e.g. REM (pressing the 'E' key). Then the DOS command can be typed in full after REM, which must be removed from the start of the line before pressing the Enter key.
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. It will be improved in future versions of the manual.
3. The TR-DOS BASIC interface uses letters 'A'..'D' to identify the disk drives, in commands and filenames. But, under the hood, TR-DOS uses numbers 0..3 to identify the disk drives, and filenames don’t include the drive letter. This is the way Solo Forth works too. Usage of A..D instead of 0..3 maybe implemented in a future version of Solo Forth, either by default or as an option.