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:

  1. 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, .lab or .lbl (and, in recent versions, .dbg from ld65). There's nothing to load by hand.
  2. /singleinstance sends 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 /debugbrkrun drops 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 .dbg file, 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 $9B as 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, /nofastboot and /nosiopatch, and with the profile that matches your real machine.

Further reading

  • Altirra's built-in help (Help > Contents) and .help in 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