Hands on

Getting Started: create your own programs

Three stages, each one optional but each more powerful: run an Apple II in your browser (2 minutes), write and save real programs in an emulator with disk images (15 minutes), and set up a modern cross-development toolchain like today's retro developers use (an evening).

Stage 1 — An Apple II in your browser (2 minutes)

1. Open Apple ][js (or its IIe sibling Apple //jse) — a faithful JavaScript emulator. No install, no sign-up.
2. You'll see the boot screen. If it sits at a spinning disk prompt, click the keyboard icon / press Reset per the page's toolbar, or just wait — with no disk it drops into BASIC with the ] prompt.
3. Type your first program:

]10 HOME
]20 PRINT "I AM PROGRAMMING A COMPUTER FROM 1977"
]30 FOR I = 1 TO 500 : NEXT
]40 GOTO 10
]RUN

Ctrl+C stops it. That's the whole loop: type, RUN, refine. Every exercise in this course can be done right here.

Other excellent emulators

For Stages 2–3, install a desktop emulator — AppleWin if you can run it. You'll want disk images and a debugger.

Stage 2 — Disks: writing programs you can keep (15 minutes)

An emulator without a disk forgets everything at power-off, like a real 1977 machine without a Disk II. The fix is a disk image: a file on your PC (usually .dsk or .po, 140KB) that the emulator treats as a floppy.

1. Download a DOS 3.3 system master image (search "DOS 3.3 system master dsk" — it's on the Internet Archive) or a blank ProDOS disk.
2. In your emulator, insert it in drive 1 and reboot: you'll get the familiar ] prompt, but now with DOS loaded above BASIC.
3. Now these commands work:

]10 PRINT "SAVED FOR POSTERITY"
]SAVE FIRST
]CATALOG

DISK VOLUME 254

 A 002 FIRST

]LOAD FIRST
]RUN

INIT HELLO on a blank disk formats it and makes it bootable. Everything you write from now on can be saved, and the disk image file on your PC is your backup — commit it to git if you like.

Stage 3 — Cross-development: the modern retro workflow

Today's Apple II developers write code in VS Code, assemble it on their PC in milliseconds, and auto-launch an emulator to test. Here's a minimal, battle-tested toolchain — all free:

Install (Linux / macOS)

# cc65 — package managers have it:
sudo apt install cc65          # Debian/Ubuntu
brew install cc65              # macOS

# AppleCommander — one jar file:
#   download ac-*.jar from https://applecommander.github.io/
#   and note its path; below we call it ac.jar

On Windows, grab the cc65 snapshot zip from the cc65 site and add its bin to PATH.

Your first cross-assembled program

Create flash.s — it inverts the top-left corner forever until a key is pressed:

; flash.s — assemble with ca65, run with BRUN FLASH
        .org  $0300           ; classic free page-3 home

KBD     = $C000               ; keyboard latch
KBDSTRB = $C010               ; keyboard strobe
SCREEN  = $0400               ; top-left of text page 1
WAIT    = $FCA8               ; ROM delay routine

start:  lda   SCREEN
        eor   #$80            ; flip normal/inverse bit
        sta   SCREEN
        lda   #$80
        jsr   WAIT            ; ~0.1s pause
        lda   KBD
        bpl   start           ; no key yet -> keep flashing
        sta   KBDSTRB         ; ack the key
        rts

Build it and disk it

# 1. assemble + link to a raw binary
cl65 -t none --start-addr 0x300 -o flash.bin flash.s

# 2. get a blank DOS 3.3 disk image (140K) — AppleCommander makes one:
java -jar ac.jar -dos140 work.dsk

# 3. copy the binary onto it as a Binary file loading at $0300
java -jar ac.jar -p work.dsk FLASH B 0x300 < flash.bin

# 4. check it landed
java -jar ac.jar -l work.dsk

Boot your emulator with a DOS system master in drive 1 and work.dsk in drive 2 (or copy the file onto a bootable disk), then:

]BRUN FLASH,D2

The corner character flashes; any key stops it. You now have the complete loop: edit → assemble → image → run, each step scriptable. Put those four commands in a Makefile and iteration time drops to about a second.

# Makefile
all: work.dsk
flash.bin: flash.s
	cl65 -t none --start-addr 0x300 -o $@ $<
work.dsk: flash.bin
	java -jar ac.jar -dos140 $@
	java -jar ac.jar -p $@ FLASH B 0x300 < $<
run: work.dsk
	applewin -d1 master.dsk -d2 work.dsk   # adjust to your emulator

Prefer BASIC? Cross-develop that too

You don't have to hand-type BASIC into the emulator. Most desktop emulators support paste: write your program in any text editor, copy it, and paste at the ] prompt — the emulator "types" it for you. Keep your .bas sources in git, paste to test, SAVE to disk image to distribute.

Level up from here

• Write C for the Apple II: the same cc65 suite compiles C — cl65 -t apple2 hello.c produces a runnable binary. Slower than assembly, vastly faster to write.
• Real assemblers with Apple lineage: Merlin32 keeps the syntax of the classic Merlin assembler used for much commercial Apple II software.
• Debugging: AppleWin's debugger (F7) gives breakpoints, memory watches, and a live disassembly — the tool 1980s developers dreamed of.
• Reading: Beneath Apple DOS, the Apple II Reference Manual ("the Red Book"), and Roger Wagner's Assembly Lines — all scanned and legally hosted at the Internet Archive.
• Community: the KansasFest conference, /r/apple2, and comp.sys.apple2 (still alive!) welcome newcomers building their first programs.

Suggested first projects

1. A boot menu — a HELLO program that lists your disk's programs and runs the one you pick. (BASIC, one evening.)
2. A drawing toy — move a lo-res cursor with I/J/K/M keys, paint with the space bar, cycle colors with C. (BASIC + direct keyboard reads.)
3. A sound keyboard — map the top row of keys to eight pitches using assembly tone routines called from BASIC. (Hybrid, the Lecture 06 pattern.)
4. A scroller — your name scrolling smoothly across the hi-res screen in assembly. (The rite of passage.)