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-card 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 new sd-card image with hdfmonkey

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

Creating new sd-card image without hdfmonkey

It's possible to use gnu coreutils and dosfstools to create card image without hdfmonkey, but depending on exact size of image these may be less compatible with various emulator, following example for 1GB card image works in MAME but fails in CSpect (while images created by hdfmonkey tool should work for both emulator, so using hdfmonkey is recommended)

truncate -s 1G NextZXOS.img
parted NextZXOS.img mklabel msdos
parted NextZXOS.img mkpart primary fat32 2048s 100%
mkfs.fat -F 32 --offset=2048 NextZXOS.img
# and now to copy files to image you have to either mount it or use hdfmonkey:
# hdfmonkey putdir NextZXOS.img tmptb /

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.

Mounting sd-card image with losetup

Alternative using losetup to use local "loop" device for mounting the image. This method can automatically detect partitions inside the image and exposes them as loop devices.

Prepare mounting dir and make sure you have mount and losetup available, Ubuntu based systems packages:

sudo apt-get install util-linux mount

Use losetup to attach image and scan its partitions

sudo losetup --partscan --show --find NextZXOS.img
# this will print new loop device and automatically create partition devices like /dev/loop0p1
# now mount the desired FAT32 partition:
sudo mount /dev/loop0p1 next-card/

Unmounting and cleanup of loop device

When finished:

sudo umount next-card/
sudo losetup -d /dev/loop0
# or `sudo losetup -D` to detach *ALL* loop devices

This detaches the loop device and frees all associated /dev/loop* entries.

Notes and gotchas:

• Do not use the image in an emulator while it is mounted.
• If the image has no partition table, --partscan will not create /dev/loop0p1.
• If multiple loop devices are active, check losetup -a to confirm which one is yours.

Mounting sd‑card image with udisksctl

The udisksctl tool provides a desktop‑friendly way to attach loop devices and mount filesystems without manually calculating offsets or using losetup. It integrates with system services such as UDisks2, and on many desktop Linux systems it allows non‑root users (who are in the correct group) to mount images safely.

Prerequisites

On Debian‑based systems install the UDisks2 tools:

sudo apt-get install udisks2

To run udisksctl without sudo, your user must belong to the disk, storage, or udisks policy group (varies by distribution). If unsure, simply use sudo in the examples below.

Attaching the image as a loop device

Use udisksctl loop-setup to create a loop device for the image:

udisksctl loop-setup --file NextZXOS.img
# prints something like:
# Mapped file NextZXOS.img as /dev/loop2.
# UDisks automatically scans the partition table and exposes partitions as:
# /dev/loop2p1
# /dev/loop2p2
# ...

Mounting the FAT32 partition

Mount the desired partition:

udisksctl mount --block-device /dev/loop2p1
# This prints the mount point, for example:
# Mounted /dev/loop2p1 at /media/youruser/NextZXOS.

You can now browse and edit the filesystem normally using your file manager or command‑line tools.

Unmounting and cleanup

udisksctl unmount --block-device /dev/loop2p1
udisksctl loop-delete --block-device /dev/loop2

This cleanly detaches the loop device and removes all /dev/loop* entries created for the image.

Notes and gotchas

• Do not use the image in an emulator while it is mounted, parallel access may corrupt data.
• If the image has no partition table, UDisks will not create /dev/loopXp1 and you must mount manually using an offset.
• Mount points are created under /media/$USER/ unless overridden by system policy.
• UDisks may auto‑mount partitions immediately after loop‑setup depending on desktop environment settings.

MAME emulator

MAME got Next emulation and it got improved a lot around end of 2025, turning it into probably most accurate and performant Next emulator currently available. But as that shift is quite recent, the developers community haven’t transitioned to it yet in large numbers and the tutorials and examples are non-existent. This section provides a basic Linux setup guide.

This chapter focuses only on installing MAME from source code git repository, so you can update to latest work in progress or even contribute to the development yourself. The stable binary releases already contain decent Next emulation, but bug fixes and improvements are still coming often and stable releases trail a few weeks behind.

At the moment, the primary developer working on Next emulation in MAME is Andrei Holub, so his fork repo will be used as default source.

Prerequisites

You need C++17 compiler (GCC 10.3+ or clang 11+), GNU make and few more development tools and common libraries, for specific list for your distro and up to date information check Compiling MAME web page from official docs.

Keep this page around as the example here is quick hint and not meant as replacement for full documentation.

Retrieving the MAME source

Use git to clone the holub's MAME repository and add the official MAME repository as an additional remote:

git clone --origin holubdev https://github.com/holub/mame.git
cd mame
git remote add -f --tags mamedev https://github.com/mamedev/mame.git

To update already cloned repository checked out at master branch, do inside the mame folder (WARNING: this will drop any local changes in the repository, as MAME devs often rewrite already published commits and you need to reset your local clone to latest state - if you are developer working on MAME sources, you should know yourself how to work with git to preserve your changes and rebase/merge):

git fetch --all --force
git reset --hard master

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

Building the executable binary

To rebuild only Next emulation ("tbblue" machine) and get executable named tbblue, run make like this:

# make sure there are no remnants from previous builds
make clean
# If you want to, you can change to TOOLS=1 to build also "various additional tools, such as chdman"
# The name of resulting binary is affected by SUBTARGET=tbblue, leave it out if you want "mame"
make REGENIE=1 EMULATOR=1 TOOLS=0 SOURCES=sinclair/specnext.cpp SUBTARGET=tbblue -j $(nproc)
# check the build output to confirm that compilation succeeded. To list binary:
ls -lh tbblue

This may take a considerable amount of time depending on how powerful your PC is.

If you are developing MAME yourself, you can do incremental build (after REGENIE=1 was used to "generate project files" in previous build and your source code changes don't require full rebuild) - this will be lot faster of course as usual:

make SUBTARGET=tbblue -j $(nproc)

To rebuild full MAME including all other emulation targets (computers and arcade machines) - which will take even much longer - use:

make clean && make REGENIE=1 EMULATOR=1 TOOLS=0 -j $(nproc)
# check existence of new binary (the line above will produce default name "mame")
ls -lh mame

Installing the executable and configuration

TODO

Checking if it all works

TODO

#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).