Set up for the ZX Spectrum
Write BASIC or assembly in the lesson. Use Build198x, Asm198x and Emu198x when you want to work with files on your own computer.
Start in your browser
Meet BASIC lets you edit a listing and run it in a Spectrum on the page. Meet Assembly lets you edit, assemble and run machine code with Asm198x and Emu198x. Neither needs a local installation or a separate ROM file to begin.
Choose either route. Assembly does not require completing BASIC first. Download your edited source before leaving the lesson so you can keep working on it.
Choose what you need locally
- Typing BASIC into a Spectrum: an emulator is enough.
- Editing a saved BASIC listing: a plain-text editor and Build198x to turn it into a tape image.
- Writing assembly: a plain-text editor and Asm198x to build the program.
Both file-based routes use a Spectrum emulator to load and run the resulting tape.
Prepare your Spectrum
On macOS or Linux with Homebrew, install the Spectrum emulator:
brew install emu198x/tap/emu198x-spectrumHomebrew chooses the binary for your processor: Apple silicon or Intel on macOS, ARM64 or x86-64 on Linux. Each Emu198x machine has its own package, so this installs only the Spectrum.
Otherwise, choose the emu198x-spectrum archive for your operating system and processor from the downloads page. Windows uses the x86-64 ZIP. Extract it into a folder you can find again.
The local emulator needs a 48K Spectrum ROM. The ROM guide explains the files and their sources. Open a terminal and start the machine, replacing the quoted path with your ROM’s location:
macOS or Linux
emu198x-spectrum --rom "path/to/48.rom"If you downloaded an archive, open a terminal in its extracted folder and use ./emu198x-spectrum instead.
Windows PowerShell, from the extracted folder
.\emu198x-spectrum.exe --rom "C:\path\to\48.rom"The Spectrum’s startup screen confirms that the emulator and ROM work together. Any other 48K Spectrum emulator that opens .tap files, such as Fuse, can also run these examples.
Build a BASIC tape
Install Build198x
macOS
If you already use Homebrew, install Build198x with:
brew install build198x/tap/build198xWithout Homebrew, use the macOS installer or archive on the Build198x release page. Choose Apple silicon or Intel to match your Mac. Extract an archive into a folder you can find again.
The commands below use build198x by name. Homebrew makes the command available automatically. If you used an archive, add the extracted folder to your shell’s PATH, or use the full path to the executable instead. From its folder, use ./build198x.
Check that your terminal can find it:
build198x --versionIf the command is not found, check the executable’s location. A version number confirms installation; the program you run next checks the whole workflow.
Windows
Open the Build198x release page and choose the Windows x86-64 ZIP (x86_64-pc-windows-msvc). Extract it into a folder you can find again.
The commands below use build198x by name. Add the extracted folder to your user Path in Windows Environment Variables, then open a new PowerShell window. To run it from that folder without changing Path, use .\build198x.exe instead.
Check that your terminal can find it:
build198x --versionIf the command is not found, check the executable’s location. A version number confirms installation; the program you run next checks the whole workflow.
Linux
If you already use Homebrew, install Build198x with:
brew install build198x/tap/build198xWithout Homebrew, use the Linux installer or archive on the Build198x release page. Choose aarch64-unknown-linux-gnu for ARM64 or x86_64-unknown-linux-gnu for x86-64 Linux. Extract an archive into a folder you can find again.
The commands below use build198x by name. Homebrew makes the command available automatically. If you used an archive, add the extracted folder to your shell’s PATH, or use the full path to the executable instead. From its folder, use ./build198x.
Check that your terminal can find it:
build198x --versionIf the command is not found, check the executable’s location. A version number confirms installation; the program you run next checks the whole workflow.
Save your downloaded BASIC listing as hello.bas. In a terminal opened in its folder, run:
build198x basic hello.bas --machine sinclair-zx-spectrum -o hello.tapBuild198x checks the listing and tokenises it into the form the Spectrum stores. hello.tap contains the program and starts it from its first line when loaded.
If the check reports an error, use its line number to find the problem in your source. Keep the spelling and spacing shown in the lesson’s listing.
Assemble a tape
Install Asm198x
macOS
If you already use Homebrew, install Asm198x with:
brew install asm198x/tap/asm198xWithout Homebrew, use the macOS installer or archive on the Asm198x release page. Choose Apple silicon or Intel to match your Mac. Extract an archive into a folder you can find again.
The commands below use asm198x by name. Homebrew makes the command available automatically. If you used an archive, add the extracted folder to your shell’s PATH, or use the full path to the executable instead. From its folder, use ./asm198x.
Check that your terminal can find it:
asm198x --versionIf the command is not found, check the executable’s location. A version number confirms installation; the program you run next checks the whole workflow.
Windows
Open the Asm198x release page and choose the Windows x86-64 ZIP (x86_64-pc-windows-msvc). Extract it into a folder you can find again.
The commands below use asm198x by name. Add the extracted folder to your user Path in Windows Environment Variables, then open a new PowerShell window. To run it from that folder without changing Path, use .\asm198x.exe instead.
Check that your terminal can find it:
asm198x --versionIf the command is not found, check the executable’s location. A version number confirms installation; the program you run next checks the whole workflow.
Linux
If you already use Homebrew, install Asm198x with:
brew install asm198x/tap/asm198xWithout Homebrew, use the Linux installer or archive on the Asm198x release page. Choose aarch64-unknown-linux-gnu for ARM64 or x86_64-unknown-linux-gnu for x86-64 Linux. Extract an archive into a folder you can find again.
The commands below use asm198x by name. Homebrew makes the command available automatically. If you used an archive, add the extracted folder to your shell’s PATH, or use the full path to the executable instead. From its folder, use ./asm198x.
Check that your terminal can find it:
asm198x --versionIf the command is not found, check the executable’s location. A version number confirms installation; the program you run next checks the whole workflow.
Download first-program.asm from the first assembly lesson. In its folder, run:
asm198x --dialect pasmo --cpu z80 --tapbas first-program.asm -o first-program.tapAsm198x reads the lesson’s Pasmo syntax and makes a tape with a BASIC loader for the machine code. You do not need to install Pasmo as well. If you already use it, see the alternative Pasmo guide.
Load, change and save
Open your tape in Emu198x. Add --tape and --autoload-tape to the startup command; use the full path if the tape is in a different folder:
emu198x-spectrum --rom "path/to/48.rom" --tape "path/to/hello.tap" --autoload-tapeFor an extracted archive, run from its folder using ./emu198x-spectrum, or .\emu198x-spectrum.exe on Windows. For assembly, use first-program.tap in place of hello.tap.
Emu198x waits for the Spectrum to start, types LOAD "" and plays the tape. Without --autoload-tape, type LOAD "" yourself and press F9 to start the tape.
Compare the result with the lesson. Change a message in BASIC, or the border colour in the assembly example, then save, rebuild and load the new tape. Keep your .bas or .asm source alongside the .tap; reopen them to check that your work is saved.