A one-click build pipeline for rapid iteration on Apple ][ software.

 

In addition to meeting lots of amazing people, the recent KansasFest left me with a strong drive to develop software for the Apple ][ platform. I did my share of it back when the machines were new, but it’s a whole different ballgame nowadays. The power of modern systems can handily remove everything about Apple ][ development that was difficult or tedious at the time, and the machine really becomes a programmer’s playground.

The first thing I wanted to do was set up a solid one-click build pipeline. That means I want to be able to go from making a change in my source code to seeing that code running on an Apple ][ with a single click (or hotkey). One of my personal cliches is that tools are a force-multiplier. It’s equally true of crowbars and software build pipelines. If you can iterate your code rapidly without thinking about it, the rate at which you produce code goes up dramatically, and the quality of that code improves. Furthermore, the fewer human steps in the pipeline, the less chance there is for human error. Problem-solving time should be spent on debugging code, not on figuring out why the compiler isn’t seeing an include file or why the device isn’t noticing your changes in the binary.

I put together this pipeline for developing Apple ][ software within Xcode, and suddenly got a lot of interest in it from the Apple ][ community. That’s always a sign that it’s time for a BlondiHacks post, so here we go. Much of the work here is based on Carrington Vanston’s process, which he demonstrated at KansasFest 2014. So, I’m standing on the shoulders of (bald) giants here.

Note that this article is not a tutorial on assembly language programming, or the Apple ][, or any of the tools involved. It’s intended as a “connect-the-dots” post for experienced programmers who want a smoother process for coding on the Apple ][. We need to do some one-time setup here that takes a bit of effort, but once that’s done, you’ll be able to crank out new Apple ][ projects with ease.

 

One Time Setup

 

Step 1: Install Xcode

 

This pipeline is based on Xcode, and the tools associated with it. I quite like the IDE, and I already have it installed for other work, so it was an obvious choice. It’s free and can be downloaded and installed from Apple. If you’re a programmer and use OS X, there’s a good chance you already have it. If not, install it from here:

https://developer.apple.com/xcode/downloads/

Why use a big modern IDE like this to develop software for a 40-year-old computer? Because modern IDEs are great, that’s why. A modern IDE eliminates all the logistical challenges of development on old hardware. The tiny screens, the tiny storage devices, unsearchable paper documentation, and the clunky primitive editors all slowed you down. Of course, for the most part we didn’t notice this at the time, because it was the best environment most microcomputer users had ever seen (cue chuckles of laughter from contemporary mainframe users). However, once you’ve developed on a 30″ screen with code-completion and a machine rated in gigahertz, there’s no going back. That genie is out of the bottle (and that GEnie was killed by the internet star).

 

Step 2: Install Virtual ][

 

One of the other ways modern systems can greatly simplify development is emulators. By keeping all the development local to one machine, you can do a lot of nice things, as we’ll see. Sure, perhaps this is “cheating”, but there’s nothing stopping you from also testing your code on real hardware periodically. The benefits of speed and automation in emulators far outweighs the loss of “purity”, in my view. An alternative pipeline would be to treat the Apple ][ as a remote debugging device, similar to how game console development is done. This is the approach I took for Veronica’s pipeline, because it was easier than writing an entire emulator from scratch for a machine that only exists in a single instance.

I don’t often use an emulator, but when I do, I prefer Virtual ][. I’m not getting compensated to say this, so believe me when I say it’s an amazing piece of work. It does everything you might want an emulator to do, and a ton of stuff you wouldn’t have expected but is surprisingly useful (the dot matrix printer emulation alone is mind-blowing). So, run don’t walk to install Virtual ][:

http://www.virtualii.com (scroll to the very bottom for download links)

Note that for this pipeline, you will need to purchase a license for the full version. This is the best money you will spend in the Apple ][ hobby, though. Support good work and buy Virtual ][!  This software does a lot, so for best results, consider reading the included documentation. I was surprised to find how much it can really do. For example, I won’t be covering the debugger here, but Virtual ][ has a complete assembly-level debugging system that will allow you to step through your code and debug it live in the emulator. Incredibly powerful!

 

Step 3: AppleCommander

 

Speaking of excellent tools, we’ll need AppleCommander. This tool is the “missing link” between compiling your code and preparing it for the emulator. The emulator wants to see disk images, because floppy disks are all that the original hardware really knew what to do with. To that end, AppleCommander is a command-line-enabled java tool that can create, modify, and otherwise manipulate all kinds of Apple ][ disk images. The sample project that I include below has a version of it included, so you don’t necessarily need to install it right away. However, you should check out the site and download the full version if you want a great tool for working with Apple ][ disk images.

http://applecommander.sourceforge.net

 

Step 4: Install cc65

 

CC65 is a collection of compilers, assemblers, linkers, and other related tools for developing software on 6502-based machines. Originally coming from the Commodore world, it has since been fleshed out in very strong fashion for Apple ][s as well. If you want to write in C, there’s no better choice. The library support is excellent, even going so far as to provide graphics and text rendering routines that are cross-platform across various 1980’s-era systems.  If you want to write assembly code (and you do), the ca65 assembler is also excellent, with full macro and expression support, debugging symbols, and many other nice features.

Installing cc65 on OS X is the trickiest part of the setup, since no simple installer exists as far as I know. The simplest way to get it, in my opinion, is through MacPorts. Type this in a terminal window:

sudo port install cc65

(it will ask you for your administrator password)

If that works, great!  If you don’t have MacPorts (most OS X systems already do), or something else goes wrong, you may have to build cc65 from source. This isn’t difficult, but may seem intimidating if you’ve never built tools from source in a Unix environment before. The best writeup I’ve seen for doing this is Carrington’s from KansasFest, so I’ll link to that here. You only need to perform steps 3 and 4 in his process:

Building cc65 from source on OS X

 

Note that cc65 is no longer officially supported by its author. However, it has a very vibrant community of users who have essentially taken it over. Links to all the documentation and such can be found at:

http://cc65.github.io/cc65/

 

Using The Pipeline

 

With all our tools in place, we can connect the dots and get the pipeline running. To help illustrate the whole thing, I’ve created a sample project you can download and open in Xcode:

Sample Xcode Project For Apple ][ development

If you have all the tools installed, then opening that project and hitting Cmd-B in Xcode will build the code and run it in Virtual ][. Note that Virtual ][ should already be running and booted into ProDOS. See the documentation in Virtual ][ if you’re unsure how to do this.  The “clean” command in Xcode (Shift-Cmd-K) will also work as expected.

The sample project is a program called “x” which prints a lot of flashing Xs on the screen. If you’re a proper Apple ][ user, this is the last time you will ever use flashing text. It was as bad an idea on 1980s computers as it was on 1990s web pages.

The Makefile and Applescript file within that sample project can be copied to any new project you want to create. Simply create an “External Build Tool” project in Xcode, and drop those two files in. You will also need an existing bootable ProDOS disk image in each project. You can copy and rename the one in the sample project.

 

The steps in the build process are:

1) Edit code as needed in Xcode

2) Click “Build”

3) Xcode assembles and links your code with ca65

4) AppleCommander copies your program into the disk image

5) Virtual ][ mounts the disk image and executes your program

 

The steps in the process are handled by make. I’m not going to give a tutorial on ‘make’ here, because it’s a complex tool with a lot you can know about it. Whole books are written about it for a reason. However, suffice it to say, Xcode can use it to build a project for you.

Here’s the Makefile that connects all these dots:

 

There are two things to know about this Makefile:

1. The name of your program is set with the PGM= line
2. The starting address in memory of your program is set by the ADDR= line. This must also match the .org statement in your assembly language code

By changing only those two statements, this Makefile should work for any basic Apple ][ project.

 

The magic that really makes this work is the Applescript at the end (included in the sample project, and shown below). Since Virtual ][ is fully Applescript-enabled, ‘make’ can be given the power to unmount and remount our disk image, reset the state of the machine, and execute our new code within the emulator. This magic also would not be possible without the command-line power of AppleCommander, which lets us modify Apple ][ disk images from within ‘make’ to set them up for Virtual ][.

 

One final note- if you want to develop with C code, this process can be tweaked to do so. Here’s a version for C:

The main differences are that using “.c” files will trigger cc65 instead of ca65, and there’s a special flag on AppleCommander (-cc65) to massage the output of the C linker into something that an Apple ][ can execute easily. This is necessary because 6502 code is generally not relocatable, and especially not so on the Apple ][. ProDOS and DOS 3.3 generally want a little header on the executable that tells it where in memory to load and run it. There are some tricky ways to make Apple ][ code relocatable, but I won’t go into that here, because it’s a whole post on its own. If you’re developing in C, the AppleScript portion of the pipeline remains the same.

 

So that’s it! I hope this process helps someone get started in Apple ][ development. A good build pipeline makes all the difference in efficiency and enjoyment of programming, so if you’re considering making Apple ][ software (and why not? It’s fun!), I hope you’ll take the time to set up a good pipeline.