Difference between revisions of "Development Tools:Linux setup"

From SpecNext official Wiki
Jump to: navigation, search
(typos and a bit of extra info)
(adding #CSpect setup notes)
Line 50: Line 50:
 
You should see version of the freshly built sjasmplus executable like this:
 
You should see version of the freshly built sjasmplus executable like this:
 
  <nowiki>SjASMPlus Z80 Cross-Assembler v1.17.0 (https://github.com/z00m128/sjasmplus)</nowiki>
 
  <nowiki>SjASMPlus Z80 Cross-Assembler v1.17.0 (https://github.com/z00m128/sjasmplus)</nowiki>
 +
 +
== #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 [https://wiki.specnext.dev/CSpect:known_bugs CSpect:known_bugs] page for more detailed report).
 +
 +
=== Prerequisites ===
 +
 +
On Debian based systems make sure you have these packages installed:
 +
<nowiki>sudo apt-get install mono-complete libopenal1</nowiki>
 +
 +
=== Retrieving the #CSpect package ===
 +
 +
Use web browser to visit blog dedicated to CSpect project [http://www.cspect.org/ www.cspect.org], find a post with latest release and download the zip file (for example <code>CSpect2_13_00.zip</code>).
 +
 +
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 (<code>~/zx/emulators/CSpect/CSpect2_13_0</code> 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:
 +
<nowiki>cd ~/zx/emulators/CSpect
 +
ln -s CSpect2_13_0 CSpect_current</nowiki>
 +
 +
Then I create launcher bash-scripts in my <code>~/.local/bin</code> like this (name of script <code>runCSpect</code>):
 +
<nowiki>#!/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=./ "$@"</nowiki>
 +
 +
Notes: I don't know any more what <code>MONO_IOMAP=all</code> 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 <code>-tv</code> 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 <code>-w4</code> will make the window quite large - 4x scale, the <code>-zxnext -s28</code> switch #CSpect into ZX Next emulation mode and set 28Mhz speed of OS as default. And finally the <code>-mmc=./ "$@"</code> 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 <code>-debug -brk -map=file.map</code>, 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:
 +
<nowiki>runCSpect beast.nex</nowiki>
 +
 +
You should see #CSpect emulator window running the beast.nex demo (or whatever else you did want to launch and entered as argument).

Revision as of 18:44, 11 December 2020

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

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)

#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

Retrieving the #CSpect package

Use web browser to visit blog dedicated to CSpect project www.cspect.org, find a post with latest release and download the zip file (for example CSpect2_13_00.zip).

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