Set up for Amiga assembly

Try a supplied Amiga program, then use Asm198x and Build198x to make a bootable disk from your own source.

Try the result first

The first Amiga assembly lesson makes the screen turn red. Its Run it here control opens the supplied disk in the browser player. Follow the player’s firmware instructions if it asks for a Kickstart ROM.

To edit and rebuild that program, use the local tools below. For programming inside the Amiga’s own language editors, follow the separate AMOS setup or Blitz BASIC setup instead.

Prepare the tools you need

A plain-text editor for your assembly source.
Asm198x to turn the source into an Amiga executable.
Build198x to put that executable on a bootable disk image.
An Amiga emulator and Kickstart ROM to run the disk locally.

Install Asm198x

macOS

If you already use Homebrew, install Asm198x with:

brew install asm198x/tap/asm198x

Without 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 --version

If 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 --version

If 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/asm198x

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

Check that your terminal can find it:

asm198x --version

If the command is not found, check the executable’s location. A version number confirms installation; the program you run next checks the whole workflow.

Install Build198x

macOS

If you already use Homebrew, install Build198x with:

brew install build198x/tap/build198x

Without 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 --version

If 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 --version

If 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/build198x

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

Check that your terminal can find it:

build198x --version

If the command is not found, check the executable’s location. A version number confirms installation; the program you run next checks the whole workflow.

For local emulation, use FS-UAE or, on Windows, WinUAE. Follow the emulator’s installation instructions for your operating system. Configure an Amiga 500 for this example and supply its Kickstart ROM; the Amiga ROM guide explains where to obtain one.

Assemble and make the disk

Copy the complete screen.asm listing from the first assembly lesson into a plain-text file with that name. Open a terminal in its folder.

First, assemble it:

Shell

asm198x --dialect vasm --exe screen.asm -o screen

Then put the executable on a bootable floppy:

Shell

build198x adf screen -o screen.adf --volume Screen

The vasm dialect names the assembly syntax; Asm198x does the assembling. Build198x writes the disk and the startup instructions that run screen.

Run it and change it

Insert screen.adf in your emulator’s DF0: drive and restart the emulated Amiga. The screen turns red.

In the source, change the colour in dc.w COLOR00,$0f00 from $0f00 to $00f0. Save the source, run both build commands again and restart with the new disk. The screen should turn green.

If you see the insert-disk screen, check that screen.adf is in DF0: and both build commands completed successfully. If an assembler error names a line, compare that line with the lesson before trying again.

Keep your work and continue

Keep screen.asm, the executable and screen.adf in the same project folder. Reopen your source and boot the disk once more to check that you can recover the work.

Continue the Amiga assembly lesson. If you already work with vasm itself, see the alternative tools guide.