Development Tools:Linux setup

General

This page collects summaries of installation process of various tools related to ZX Spectrum Next software development for linux OS users.

As usual with linux, most of the suggestions are in the form of command line command to be used from terminal.

sjasmplus assembler

You can also check the video of installing sjasmplus on freshly reinstalled KDE neon 5.20 linux, where is also extended info how to run the automated tests of sjasmplus, and opening it in KDevelop IDE to eventually write your own modifications.

Prerequisites

On Debian based systems make sure you have these packages installed (git-cola and cmake are optional, but often handy):

sudo apt-get install git build-essential g++ git-cola cmake

Retrieving the sjasmplus source

Use git to clone the z00m's sjasmplus repository:

git clone --recursive -j8 https://github.com/z00m128/sjasmplus.git

To update already cloned repository, do inside the sjasmplus folder:

git pull

- or use your favourite GIT client app to update the cloned repository.

Building the executable binary

The GNU make and common C++ compiler (gcc or clang) should be enough to build the binary:

make clean && make

To verify the binary was built ("dot slash" prefix to force running of binary in current folder, not system one):

./sjasmplus --version

Installing the executable

If you already have sjasmplus installed, use which sjasmplus to see where the installed executable is (and which installed executable has precedence), you can use this command also after installing the new executable to verify it is being picked up by the system.

Installing the binary in system-wide fashion:

sudo make install

Or you can install the binary only locally for your user (without root/sudo permissions):

mkdir -p ~/.local/bin
make PREFIX=~/.local install

- then make sure you have ~/.local/bin in your user PATH environment variable (on some distros there is already script in .profile to add this to PATH if the dir does exist, so you may need to only logout/restart after creating it to get it active).

Checking if it all works

Open your terminal and type (in any directory):

sjasmplus --version

You should see version of the freshly built sjasmplus executable like this:

SjASMPlus Z80 Cross-Assembler v1.17.0 (https://github.com/z00m128/sjasmplus)

hdfmonkey tool

The hdfmonkey tool can manipulate card-images, helping to write new builds of your project into NextZXOS card-image, to boot the emulators with full file system. (it's also possible to mount the images directly into linux by other means, to operate on them with regular file manager/etc, but hdfmonkey suits better use-case when the build script does update the image)

Prerequisites

On Debian based systems make sure you have these packages installed:

sudo apt-get install git build-essential g++ autoconf

Retrieving the hdfmonkey source

Use git to clone the hdfmonkey repository with patched 0.5.7 jjjs version sources:

git clone https://github.com/ped7g/hdfmonkey.git

(make sure you are on the default branch "jjjs-variant" to build the improved version, it should be checked out by default after clone)

• to update already cloned repository, do inside the hdfmonkey folder:

 git pull

• or use your favourite GIT client app to update the cloned repository.
• if you cloned original gasman's repository before, you may want to clone and rebuild here mentioned jjjs version to get multiple fixes and convenience features.

Building the executable binary

The hdfmonkey is using autoconf/autotools to build final Makefile, check the hdfmonkey README for "from git" installation notes, at the moment of writing this page, the steps were:

cd hdfmonkey
autoheader
aclocal
autoconf
automake -a
./configure
make

To verify the binary was built:

src/hdfmonkey help

Installing the executable

If you already have hdfmonkey installed, use which hdfmonkey to see where the installed executable is (and which installed executable has precedence), you can use this command also after installing the new executable to verify it is being picked up by the system.

Installing the binary in system-wide fashion:

sudo make install

Or you can install the binary only locally for your user (without root/sudo permissions):

make prefix=~/.local install

- then make sure you have ~/.local/bin in your user PATH environment variable.

Checking if it all works

Open your terminal and type (in any directory):

hdfmonkey help

You should see help of the freshly built hdfmonkey `jjjs version` executable like this:

hdfmonkey: utility for manipulating HDF disk images v0.5.7 jjjs

usage: hdfmonkey <command> [args]
...

Extracting all files from the SD image

7-zip is the most convenient tool to extract the the files from the existing image.

To install 7-zip on a Debian system use sudo apt install 7zip.

To extract all the files from an existing image tbblue.img to a new subdirectory myfiles:

7z x tbblue.img -omyfiles

Creating a new SD image from the archive

This example:

• downloads the archive from the specnext.com
• unpacks it to the subdirectory tmptb
• creates a new SD image (with the space for 2GB files) from all the files
• deletes the subdirectory tmptb
• shows that the new image uses much less than 2GB
• starts listing the content of the newly created image

wget https://www.specnext.com/distro/24.11/sn-complete-24.11.zip
7z x sn-complete-24.11.zip -otmptb
hdfmonkey create tbblue.img 2GB
hdfmonkey putdir tbblue.img tmptb /  
rm -rf tmptb
du -h tbblue.img
7z l tbblue.img | more

Mounting sd-card image directly

Sometimes it may be useful to mount the card image directly, to be able to browse it and manipulate with common tools. But make sure you are not using mounted card image also in emulator at the same time, to prevent any data damage by parallel access.

Prerequisites

On Debian based systems make sure you have these packages installed:

sudo apt-get install fdisk mount

Prepare empty directory to mount the card image into (let's call it "next-card") and have the image file around ("tbblue.mmc" in following examples)

mkdir -p next-card

Mounting the card image

To mount the card image you need to know the exact byte-offset where the FAT partition starts, it's possible to read it from "fdisk" or "parted" tools outputs:

fdisk -l -o Start tbblue.mmc
# prints value in sector units, like:
# Start
#    63
# This has to be multiplied by 512 to get byte offset: 63*512 = 32256

# or

parted tbblue.mmc unit B print
# prints values in bytes with "B" suffix in "Start" column

But the fdisk output can be incorporated directly into mount command, which needs root permissions, example with sudo:

sudo mount tbblue.mmc next-card/ -o loop,offset=$((`fdisk -l -o Start tbblue.mmc | tail -1` * 512)),user,uid=`id -u`,gid=`id -g`

# or you can enter the offset yourself

sudo mount tbblue.mmc next-card/ -o loop,offset=32256,user,uid=`id -u`,gid=`id -g`

The uid and gid options will mount the filesystem under your regular user, so you can now browse it with file manager, text editors, etc.

Do not run the emulator yet, before unmounting the image (after you are done manipulating the files)!

Unmount the image before using it in emulator

sudo umount next-card/

Check the result. If the unmounting fails (probably with "target is busy"), find which process is still accessing/viewing the files in the next-card directory, and try to unmount it again.

TODO: udiskctl loop device mounting option

From discord: "udisksctl loop-setup --file ~/spec/SpectrumNext/tbblue/image/tbblue.mmc"

TODO: describe this solution and check possible gotchas/CLI options (like user must be in udiskctl group to run this without sudo, etc).

#CSpect emulator

The #CSpect is Mike Dailly's ZX Spectrum Next emulator, written in C# making it cross-platform (sort of, where the mono framework is available). It is non-free (closed-source, custom license) project, but available for usage without any payment (it's possible to use it internally to develop also commercial titles, but you can not distribute/sell the emulator itself, not even packaged with your game - for such agreement contact the author first and get his permission).

Currently it is most performant and user friendly emulator of ZX Spectrum Next, with good emulation accuracy (see CSpect:known_bugs page for more detailed report).

Prerequisites

On Debian based systems make sure you have these packages installed:

sudo apt-get install mono-complete libopenal1 libsdl2-dev

Retrieving the #CSpect package

Use web browser to visit itch.io dedicated to CSpect project mdf200.itch.io/cspect and download latest release.

You may get warnings from your browser or antivirus about the page itself and about the zip/binary files. The #CSpect has long record of triggering false positives of AV engines due to the executable being not digitally signed and because of the code using features of OS which are normal for emulator, but may look wonky for AV heuristic. Whether you trust the executable is virus free is up to you, in the end.

Installing the executable

Unzip the retrieved zip file (I personally use KDE Dolphin file manager, the file context menu "Extract -> Extract archive here, autodetect subfolder"), and place the unzipped directory to target destination (~/zx/emulators/CSpect/CSpect2_13_0 in my case). I prefer to keep every version in its own directory, and have general symbolic link pointing to the one I want use by default:

cd ~/zx/emulators/CSpect
ln -s CSpect2_13_0 CSpect_current

Then I create launcher bash-scripts in my ~/.local/bin like this (name of script runCSpect):

#!/bin/bash
# personal script of Ped to launch "#CSpect" emulator in "current directory" (with arguments like: "runCSpect file.nex")
MONO_IOMAP=all mono ~/zx/emulators/CSpect/CSpect_current/CSpect.exe -tv -zxnext -s28 -w4 -mmc=./ "$@"

Notes: I don't know any more what MONO_IOMAP=all helps with, I believe it was suggested to help with any filesystem windows-like paths containing backslashes, you can try to do your own research. The -tv switch will switch off "scanlines" shader effect and generally switch off any GPU shaders, which makes CSpect more compatible with graphics drivers (try it, if you get only black screen or instant crash during init). The -w4 will make the window quite large - 4x scale, the -zxnext -s28 switch #CSpect into ZX Next emulation mode and set 28Mhz speed of OS as default. And finally the -mmc=./ "$@" will set current directory for esxdos emulation to the directory where you use the script to launch the emulator, and pass any remaining command line options entered by user, like the name of the SNA/NEX file. Other noteworthy options are -debug -brk -map=file.map, the -debug entering the debugger just ahead of the first instruction, -brk enables CSpect specific two-byte tag 0xDD 0x01 to work as breakpoint and the -map option allows you to load into debugger the symbol table from your assembler (directive CSPECTMAP in sjasmplus), making labels visible in disassembly.

Checking if it all works

Go to some directory with SNA/SNX/NEX file (there are also some demo files right in the CSpect directory) and use the launcher script, like:

runCSpect beast.nex

You should see #CSpect emulator window running the beast.nex demo (or whatever else you did want to launch and entered as argument).