Cross-development

Everything up to here happens at the machine: you type a line, press Enter, and something happens. That is the best way to learn a computer and a fine way to write a short program.

This half is for when you want more room. Cross-development means writing your program on your own computer — in your own editor, under version control — and building it into something the ACE loads. It is how you write assembly. It is how you write anything longer than a screenful. And it is how you get a program to run and check itself while you are still typing.

What you end up with

6502 run build/countdown.prg

A window opens, the machine boots, and your program runs. Take the window away and the same build runs in your terminal, prints what it printed, and tells you whether it worked:

$ printf '\rRUN\r' | 6502 run --headless --exit-on 'LIFT OFF' --timeout 20s build/countdown.prg

That second form is the interesting one. It turns "does my program work" into a question a script can answer, which is what makes a test suite possible.

One program, four ways to the machine. The chapters that follow take them one at a time.

What you need

Three things, and two of them are already on your computer:

A text editor	Whichever one you already use
cc65	The assembler and linker — installing it has one trap in it
The 6502 command	The emulator, driven from a terminal

There is no ACE in that list. You can do every chapter here with nothing but a laptop, and move to hardware when you are ready — that is a chapter of its own.

Everything works the same on macOS, Linux and Windows.

The chapters

Chapter	What you get out of it
Why cross-develop	What the loop looks like, and when to stay at the machine instead
Installing cc65	The assembler, and the one version trap in this ecosystem
The tool belt	Six tools, what each is for, and how to prove each one works
Starting from a template	Clone a working project instead of building one
The Makefile	Every target, and how to add your own
The linker config	Why a program starts at $0800 and a cartridge at $C000
Build, run, repeat	The loop itself, windowed and headless
Debugging	Breakpoints, registers, memory, and stepping through your own labels
Testing your program	A suite that boots once and runs every case in a second
Onto real hardware	Memory card, serial cable, Wozmon paste, EEPROM
BASIC from your editor	Write listings as text, keep them in version control
Driving it from an agent	The machine as something a program can operate

If you are here to write assembly, this section is the part that gets your build working. What to write once it does — the 65C02 itself, and the Kernal routines your program calls — is the assembly guide, and it comes next.