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.
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:
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).
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!
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.
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:
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:
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.
10 thoughts on “Apple ][ Development on OS X”
“I don’t often use an emulator, but when I do, I prefer Virtual ][” should have been said in the form of a meme picture of yourself, in the same position and facial expression as the Dos Equis guy.
Hah, yes I’ll concede that was a missed opportunity for a sight gag. If I wasn’t so disinclined to put photos of myself on this blog, I might oblige.
This is so phenomenally great I can’t say how phenomenally great it is. Thanks.
Apple IIc + make. Never thought I’d see the day. Nice hack Q.
Thanks! I’m just gettin’ warmed up with this baby. 😉
A few quibbles/tips from an old geezer Unix hacker –
As of OSX Lion, the simplest way to get Xcode is through the Mac App store. It’s free and will keep itself updated that way.
MacPorts isn’t on OSX machines by default. Get it from macports.org. Whether getting MacPorts working is preferable to compiling the 65xx compiler from source for most of your readers I can’t say.
As of Mavericks I hit a wonky way Apple gets you to read and agree to the proper license for some command line tools – trying “sudo make –version” in a terminal window might save a lot of headbanging if OSX doesn’t think you’ve agreed to the license already. If all it does is print out some info you’re home free.
(And no, I’ve never even used an Apple ][ but your adventures are still fun reading. If I ever built my own version of something old, it’d probably be a PDP-8 clone. I said I was old.)
In my “sudo make –version” suggestion, that’s two dashes before version.
Those are excellent tips- thanks for sharing! Of course, I totally forgot that Xcode is in the App Store now. That is the easiest way to get it, I agree.
What you describe is vaguely similar to the development chain I use with my POC SBC. In this case, I send a stream of Motorola S-records to POC via a TIA-232 link from my UNIX box on which I do 65xx development.
After assembling the program destined for the POC unit, S-record output is written into what appears to be a regular file, but is actually a named pipe (aka FIFO). The other end of the FIFO is read by a C program (S-record driver), which sleeps on waiting for the FIFO to be opened for writing. When that happens, the C program buffers the input record by record and writes to the TIA-232 device.
Meanwhile on POC, the S-record loader, which is built into the firmware and started before assembler output is written to the FIFO, awaits incoming S-records. As received from the UNIX box, each S-record is terminate by ASCII ($0A). The incoming S-record is error-checked and if okay, translated into bytes and stored in RAM. The process continues until the UNIX S-record driver detects EOF from the FIFO, at which time an ASCII ($04) is sent to POC, telling it that all data has been transmitted. The driver then goes back to sleep and POC terminates the S-record loader and returns control to the machine language monitor.
I currently have the TIA-232 link running at 230.4 Kbps, so the load is pretty quick. It’s about as painless and efficient as I can make it and produces an almost-interactive development environment.
That’s great! It actually sounds closer to the process I used for Veronica (http://quinndunki.com/blondihacks/?p=1284). It was all about tricking the AVR programmer into tricking the EEPROM burner into flashing my new code without having to do anything on either the host or target machine. Your system also sounds a lot like ADT Pro, which is a really nifty piece of software than can download code directly into RAM on an Apple ][. It’s intended for bootstrapping a machine that you bought on eBay but didn’t come with any floppy disks. However, I’m sure it could be used for remote target development as well. One of these days I’ll try that…
Comments are closed.