The tool belt

Six tools. One is required, one you will want within the hour, and the rest solve a specific problem each — install those when you hit the problem.

Tool	For	Needed
cc65	Assembling and linking	Always
6502	Running your build without hardware	Nearly always
bastok	BASIC text ⇄ the tokenized form the machine loads	Writing BASIC in an editor
cffs	Building CompactFlash images	Getting files onto a card
bin2woz	Turning a binary into something you can paste over serial	No card, no cable adapter
minipro	Burning EEPROMs	Making cartridges

The 6502 command

The emulator's desktop app installs it: Settings → Command Line → Install. That is the whole installation — the CLI lives inside the app, so the two can never drift apart in version.

6502 --version

3.3.0

If you don't have the app yet, it's on the releases page, and The emulator covers what it does with a window open. Here it is a build tool: it boots your program, prints what the program printed, and exits with a status.

6502 run --help
6502 dbg --help

Those two are worth reading once, early. Everything in the next six chapters is in them.

bastok

Converts a BASIC listing you typed in a text editor into the compact tokenized image the machine's LOAD expects — and back again, which is what makes listings diffable.

npm install -g bastok

bastok -b 2 game.txt     # text → game.prg
bastok -b 2 game.prg     # program → game.txt
bastok -T -b 2           # print the token table

It works out the direction from the file extension. Give it -b 2 every time. BIOS 2.0 added keywords, and bastok starts from the older machine's table unless told otherwise. A listing that uses SCREEN or NVSAVE comes out wrong without it (bastok prints a warning naming the line), while one that doesn't comes out the same either way, which is how a missing -b 2 hides in a build script until the day a program needs a new keyword. BASIC from your editor is the chapter that uses it.

cffs

Builds the disk images the ACE's CompactFlash card holds — up to 256 disk banks of a megabyte each, matching what DISK n selects on the machine.

npm install -g cffs-image-tool

cffs create disk.img --size 1M
cffs add disk.img GAME.PRG
cffs list disk.img
cffs extract disk.img GAME.PRG recovered.prg

The package is called cffs-image-tool; the command it installs is cffs. Write the image to a real card with your operating system's usual disk writer, and the ACE reads it. See Onto real hardware.

bin2woz

Turns a binary into ADDR: XX XX XX deposit lines — the format Wozmon understands. Paste them into a terminal and the bytes land in memory, with no card and no file transfer protocol involved.

npm install -g bin2woz

bin2woz -a 0x0800 build/countdown.prg > countdown.woz

0800: 0A 08 0A 00 A5 32 30 36 30 00 00 00 A9 0A 85 40
0810: A5 40 A2 00 20 96 A0 20 93 A0 C6 40 D0 F2 A9 26
0820: A0 08 20 90 A0 60 4C 49 46 54 20 4F 46 46 0D 0A
0830: 00

It is the crudest way to move code and the one that needs the least. There is a catch if you then want BASIC's RUN to work.

minipro

Drives a TL866-family programmer, for burning cartridge ROMs onto an AT28C256.

brew install minipro          # or your distribution's package

minipro -p AT28C256 -w Cart.crt

Only needed if you are making real cartridges. The emulator takes a .crt file directly with --cart, so you can develop the whole thing without ever burning a chip.

The character editor

TMS9918-EDITOR runs in a browser — nothing to install. Draw 8×8 character patterns, lay out screens, animate sprites, and export the result as ca65 assembly, BASIC DATA statements, raw binary, or a PNG. It was made for the TMS9918A, the chip this machine's video card grew out of, so it draws one-bit patterns with a color pair — which is exactly what text mode, and a one-bit layer in any graphics layout, takes. For 2- and 4-bit tiles it is a starting point rather than the whole job.

Checking the lot

Paste this in and you have your answer for all six:

cl65 --version
6502 --version
bastok --version
cffs --version
bin2woz --version
minipro --version

Missing tools print "command not found", which is the point. For cc65 there is a second question the version string can't answer — see Don't trust the version string.

Next: clone a project that already works.