Skip to content

40.Upgrading_vForth

Jump to bottom
Matteo Vitturi edited this page Mar 15, 2025 · 3 revisions

How to upgrade vForth

This document how to upgrade vForth without losing any data.

Assumptions before you start

I'll assume your vForth directory is inside C:/tools/vForth so change it to where it is on your SD card.

Generally it's best not to put your own files inside the vForth directory, but instead inside another directory, like C:/home. If you do have your own files inside C:/tools/vForth directory, you'll need to take care of copying these across to the new vForth folder on the SD Card once you've copied the SD Card.

However, the blocks file !Blocks-64.bin is inside your vForth folder. If you've editted blocks, then this will have been changed. More about this later.

Backup your Existing vForth folder

We are assuming that we will upgrade having taken out the SD Card out of your Spectrum Next and inserted it into your main computer. Make sure you save any data, and turn off your Spectrum Next before removing the SD Card.

Hopefully your main computer will recognise the SD Card and you can see the directories like apps, demos, home, game and more. One of those should be tools since you've installed

Backup your vForth directory to your local computer hard drive. You just drag it to a local document or home folder. I usually add the date and time to the vForth filename and also zip archive the folder.

Once you are happy you have a full backup copy off the SD Card, then you can either:

  1. Rename the vForth directory on the SD card (say vForth-old-dd-mon-year).
  2. Delete the vForth directory - if you are REALLY sure you have everything.

There is usually plenty of space, so I tend to just rename it.

NOTE: SD Cards are generally terrible at long term storage without becoming corrupt. You should consider backing up your SD Card periodically. ``

Download a new Copy and Install

This is the same as '00.Home.md - HOW TO START'

  1. Download the latest .zip file from Project Download directory https://github.com/mattsteeldue/vforth-next/tree/master/download

  2. Copy from inside the .zip file to Next's SD card the whole "vForth" directory to C:/tools/vForth, and the dot command in C:/dot 2.1. In common Linux systems, you have to mount the SD card somewhere, there is a nice how-to here: https://unix.stackexchange.com/questions/316401/how-to-mount-a-disk-image-from-the-command-line 2.2. In Windows systems, you better use hdfm-gooey.exe.

  3. Forth System is loaded and activated by the Basic program C:/tools/vForth/forth17_loader.bas or via dot command .vforth. There is also a .term0 which is the Raspberry Pi Terminal.

  4. Previous version should be activated using the corresponding loader.

Recovering and Merging Edited Blocks

If you have edited blocks on your vForth directory then you will need to consider whether you want these blocks on your new installation.

If you don't care about any previous blocks, then you can skip this step.

Usually the blocks file is changed during an update - so simply copying across your old file is not good idea.

How to copy blocks

Ideally, we need a utility that copies blocks changes between releases... perhaps we should make a merge utility.

Inside the vForth project (not the install zip) is a folder called util.

This contains two utilities in Perl (text files, that run under Perl programming language).

  • blocks2txt.pl extracts blocks from a blocks file.
  • putscr.pl puts code back into a blocks file.

Read the top of these two files using your favourite text editor to find out how they work.

For instance the first utility perl blocks2txt.pl !Blocks-64.bin 1000 will produce a text file with the contents of the first 1000 screens (two Blocks forms one Screen) - so you can get your code back! The output is structured in numbered Screens, 16 rows each, each row don't execeed 64 characters in length.

The second utility performs the reverse operation using (part of) the text file produced by the first utility and trying to fit it in the Screens where they belong.

For example, if you inadvertently had corrupted the standard message blocks (see Screens from #4 to #8) you can restore them using perl putscr.pl Standard_Messages.txt !Blocks-64.bin 4, in this case, the text file Standard_Messages.txt was extracted from the output of the first utility executed beforehand.

Using vForth itself, you can extract blocks to SD text (or binary) file or import from file, using

  • load2block.f to import a single block from file
  • load2scr.f to import two contiguous blocks that forms a screen.
  • screen-from-file.f to export a screen to file.

At some point there will be better instructions here...

Finally...

Can put your SD Card and try to use your vForth next as usual.

If you can't remember anything, then you can look at: '00.Home.md - HOW TO START'

Also see Quickstart

vForth-Next - a Sinclair ZX Spectrum Next Forth

Clone this wiki locally