A Modern Cross-Development Workflow for the Atari 8-bit
Most new Atari 8-bit software is now written on a modern computer. You edit with a real text editor, assemble or compile in a fraction of a second, test in a cycle-accurate emulator, and copy the result to real hardware only at the end. This guide puts the pieces together into a loop of edit, build, run and debug that takes seconds, not minutes.
What you'll learn: choosing a toolchain, editor integration (VS Code and WUDSN/Eclipse), driving Altirra from the command line, repeatable machine configurations, automatic symbols, making disk images, and testing on hardware.
What you need: a PC, one assembler or compiler (see the MADS, ATasm and cc65 guides), Altirra, and optionally make or another task runner.
1. Pick a toolchain
| Tool | Best for | Debug symbols in Altirra |
|---|---|---|
| MADS | Assembly. Most modern Atari game and demo code uses it. Macros, procedures, 65816, SpartaDOS X output | Labels, listing and source-level |
| ATasm | Keeping or porting MAC/65-style source | Labels only |
| XASM | Compact, simple syntax (MADS borrows from it) | Labels, listing and source-level |
| cc65 (cl65/ca65/ld65) | C, or large modular projects mixing C and assembly | ld65 .dbg debug files |
Put the tool's bin folder on your PATH so every editor and script can find it.
2. Editor integration
WUDSN IDE (Eclipse). This free Eclipse plug-in offers syntax highlighting, assembling inside the editor with error navigation, an outline of macros and sections, code completion, hyperlinks to include files, and generation of label files for emulators. Long-time users still praise its outline view. The cost is the size of Eclipse itself.
Visual Studio Code. There are several Marketplace extensions: a MADS syntax highlighter (mirao.mads), "Atasm Altirra Bridge" (which, despite the name, also builds with MADS and launches Altirra), plus FastBasic and cc65 helpers. You can do without any of them by writing a tasks.json. A minimal one:
{
"version": "2.0.0",
"tasks": [
{
"label": "Build - MADS",
"type": "shell",
"command": "mads",
"args": ["${fileBasename}", "-l", "-o:${fileBasenameNoExtension}.com"],
"group": "build"
},
{
"label": "Build - ATASM",
"type": "shell",
"command": "atasm",
"args": ["${relativeFile}", "-mae", "-Iincludes",
"-o${fileBasenameNoExtension}.com"],
"group": "build"
}
]
}
Press Ctrl+Shift+B and choose an assembler. Add a problemMatcher that matches your assembler's error format and clicking an error will take you to the line.
Whatever editor you use, keep the project in git. The source is plain text, and binary assets (fonts, maps, music) are small.
3. Build with a script, not by hand
A Makefile (or a batch or shell script) records exactly how to build the program and lets the editor, the command line and CI all build it the same way:
AS = mads
ALTIRRA = Altirra64.exe
game.xex: game.asm $(wildcard inc/*.asm) gfx/font.fnt
$(AS) game.asm -o:game.xex -l:game.lst -t:game.lab -i:inc
run: game.xex
$(ALTIRRA) /singleinstance /run game.xex
debug: game.xex
$(ALTIRRA) /singleinstance /debug /debugbrkrun /run game.xex
Two details make this work well:
- Name the symbol files after the executable. When Altirra boots a program, it automatically loads files with the same base name and the extensions
.lst,.labor.lbl(and, in recent versions,.dbgfrom ld65). There's nothing to load by hand. /singleinstancesends the new image to an Altirra window that is already open instead of starting another one, so your window layout, breakpoints and debugger panes stay where they were.
For cc65 the equivalent build line is:
cl65 -t atari -g -O -Wl --dbgfile,game.dbg -m game.map -o game.xex src/*.c src/*.s
4. Drive Altirra from the command line
These switches are listed in Altirra's own cmdhelp.txt. Put them in your run and debug targets so every test starts from a known machine:
| Switch | Use |
|---|---|
/run <image> |
Run an executable. /runbas runs a BASIC program, /disk and /cart mount images, /tape loads a cassette image |
/debug |
Start in debugger mode |
/[no]debugbrkrun |
Break into the debugger at the EXE run address |
/debugcmd:<command> |
Run a debugger command at start-up, e.g. a breakpoint |
/defprofile:800\|xl\|xegs\|1200xl\|5200 |
Use the default profile for a machine type |
/hardware:800\|800xl\|5200 , /memsize:16K…1088K |
Test on smaller or bigger machines |
/kernel:osa\|osb\|xl\|… , /[no]basic |
Pick the OS ROM. Turn internal BASIC off or on |
/ntsc , /pal |
Check timing on both video standards |
/[no]stereo |
Dual POKEY |
/hdpath <path> / /hdpathrw <path> |
Mount a PC folder as the H: device (read-only or read/write) |
/tempprofile , /portabletemp |
Run without saving settings changes (good for automated tests) |
/type "keys" |
Type into the emulated keyboard (~ = RETURN) |
For example, to check that a program still fits and runs on a 48K Atari 800 with OS-B under PAL:
Altirra64.exe /defprofile:800 /kernel:osb /memsize:48K /pal /run game.xex
Altirra also accepts virtual paths such as zip://build.zip!game.xex, which runs a file straight out of an archive.
5. Debug efficiently
With symbols loaded you can break on labels (bp main.loop), watch variables every frame (wx db score), break when a location is written (ba w $D01A), and step through source with F10/F11. See the Altirra debugger guide. Two features suit a scripted workflow especially well:
/debugcmd:"bp main"combined with/debugbrkrundrops you at the right spot every time..onexerun <command>queues a command for the moment the run vector fires. Unlike/debugbrkrun, it can be any command, a.printf, say.
6. Make disk images and test on hardware
Eventually you'll want an ATR. HiassofT's dir2atr (part of his Atari tools collection) builds an image from a directory. An example from an xBIOS project:
dir2atr -m -B xboot.obx 1040 test.atr testdir
Here 1040 is the sector count of a 130K "enhanced density" image, testdir holds the files to copy in, and the other switches chose the file system and a custom boot loader. Run dir2atr with no arguments to see its full option list before you rely on them. For a plain DOS 2.5 disk, copy your XEX onto an existing DOS image in Altirra using the H: device, or mount the image from the PC side with your favourite ATR tool.
For real hardware there are many ways to load XEX files without copying anything to floppies: SIO2PC software such as RespeQt, FujiNet, SDrive-class SD-card devices and the SIDE cartridges' XEX loaders. Test on at least one real machine before release. Emulators are very accurate now, but real disk timing, loaders and PAL/NTSC differences still catch people out.
7. Graphics, fonts and music tools
The usual PC-side helpers are EnvisionPC (font and map editor modelled on APX Envision), Graph2Font (G2F) and Atari Interlace Studio for converting and editing pictures in Atari modes, FAIL/RECOIL for viewing native Atari picture formats on a PC, and ATASCII-aware editors and converters. Export as raw binary and pull the data in with ins (MADS), .INCBIN (ATasm) or .incbin (ca65).
Troubleshooting
- No symbols in the debugger. The symbol file's base name doesn't match the executable, or it's in another folder. Load it by hand with
.loadsym file.lab. For ca65, use an ld65.dbgfile, not a listing. - A new Altirra window opens for every build. Add
/singleinstance(or/si). - The build "works" but runs old code. The task builds a different file from the one you're editing (VS Code's
${file}and${relativeFile}vs${fileBasename}), or make didn't see a changed include. List every include as a dependency. - Text files look wrong on the Atari. ATASCII uses
$9Bas end-of-line. Use Altirra's H6:–H9: devices, which convert line endings, or a converter. - Works in the emulator, fails on hardware. Retest in Altirra with
/accuratedisk,/nofastbootand/nosiopatch, and with the profile that matches your real machine.
Further reading
- Altirra's built-in help (Help > Contents) and
.helpin the debugger. - The MADS, ATasm, cc65 and Altirra debugger guides on this site.
- Mapping the Atari (Ian Chadwick, COMPUTE! Books, 1983). It's on the desk of every Atari programmer, cross-development or not.
Credits
- Altirra command-line help (cmdhelp.txt) and debugger help (Altirra 4.40 source) — Screenshot from Avery Lee's Altirra page, virtualdub.org
- AtariAge — WUDSN IDE: The free integrated Atari 8-bit development plugin for Eclipse — AtariAge forum members
- AtariAge — Visual Studio Code — AtariAge forum members
- AtariAge — MADS in Visual Studio Code — AtariAge forum members
- AtariAge — Windows Tools for Atari Programming — AtariAge forum members
- AtariAge — Load Data from disk in Assembly (dir2atr usage) — AtariAge forum members
- MADS usage; cc65 cl65/ld65 docs; ATasm manual — JAC; mads.atari8.info
- comp.sys.atari.8bit FAQ — modern storage devices and XEX loaders — Michael Current (comp.sys.atari.8bit FAQ)
