MPW, Carbon and building Classic Mac OS apps in OS X

January 24 2015


In 2014 I came across a project on Github described as “Macintosh Programmer’s Workshop (mpw) compatibility layer”.

There has never been a good way to compile Classic Mac OS apps on modern OS X — for the most part, you were stuck using ancient tools, either Apple’s MPW or CodeWarrior, running in a VM of some sort. CodeWarrior, of course, is not free, and MPW only runs on Classic Mac OS, which is unstable at the best of times and downright nightmarish when trying to use it for development in an emulator like SheepShaver.

Enter ‘mpw’ (which I will refer to in lowercase throughout as something distinct from Apple’s MPW toolset).


mpw is an m68k binary translator/emulator whose sole purpose is to try and emulate enough of Classic Mac OS to run MPW’s own tools directly on OS X. MPW is unique in that it provided a shell and set of commandline tools on Classic Mac OS (an OS which itself has no notion of shells or commandlines) — this makes it particularly suited to an emulation process like mpw attempts to provide, as emulating a commandline app is a lot easier than one built for UI.

At the time I came across the project, the author himself had never attempted using mpw to build a Classic MacOS app — only commandline tools and Apple II-related stuff. Naturally, building a UI app was the first thing I’d try.

The Experiment

I started off by writing code just to see how well mpw emulated the MPW compilers, and over time managed to write a working shim of an app that could run on System 1.1g. This in itself was a learning process, not only in code but in piecing together the build process. All the sample code and documentation of the time was in Pascal, so I had to translate that to C — not so difficult, it turns out (technically, first I had to transcribe it from a PDF…).

Sample app running in Mini vMac

Eventually I had something that worked, built a few sample projects, uploaded some to Github and left the classic Mac stuff for a while.

More recently, towards the end of 2014, mpw added support for the PowerPC tools, so I immediately set out to update my build processes to support that — a trivial effort.

However, now that it was possible, I really wanted to try Carbonization.

Why Carbon?

I vaguely knew what Carbon was from having lived through the OS 9 -> OS X transition, and that knowledge came with a certain amount of bias. “Carbon is that thing that badly ported OS 9 apps used, right?” It always felt 'off’ in OS X, in the same way that cross-platform UI toolkits invariably feel off.

I knew I wanted to understand the process better, however, and see what would be involved in porting my sample projects to Carbon (and thusly, OS X). I read some books, and set to work.

The actual porting process didn’t take much time at all, and for the most part I ended up with fewer lines of code than where I started. Most of the changes involved #ifdef-ing out lines of code that weren’t necessary anymore, and changing anything that directly accessed system structs to using accessor functions — a trivial amount of work (for an admittedly trivial set of projects).

Carbon code

What interested me the most is how so much of the API remained identical — I was still using only functions that existed on System 1.0 in my app, but they were working just the same as ever in a Carbonized version. The single built binary ran on OS 8.1 all the way to 10.6 (care of Rosetta).

My mind wandered to Carbon as it exists in 10.10. While Apple decided not to port it to 64-bit (for all the right reasons), the 32-bit version of Carbon is still here in the latest release of OS X — I wondered how much of it was intact.

Turns out the answer is: all of it.

The only change I had to make was to point my header includes at the right place, but after that the whole app came to life exactly as it did on Classic Mac OS.

Carbon ifdef

With the same source file, and only a handful of #ifdefs, I could build the same app for 1984’s System 1.0 all the way up to the current release of OS X, Yosemite.

Carbon app running on Yosemite and Mac OS 1.0

The Sample Project

Just to provide an example for this post, I put together a trivial drawing app called BitPaint. It isn’t very interesting, but it should illustrate a few things:

  1. What’s involved in bringing a trivial classic Mac app to Carbon
  2. How the Classic Mac OS build process works
  3. How much source compatibility exists between 1984’s Toolbox and Carbon today

Carbon, redux

The more I dug into it, the more I came to the conclusion that Carbon was probably one of the most important things Apple did in building OS X. Even today it provides source compatibility for a huge chunk of the classic Mac OS software base. It kept the big companies from ditching Apple outright when they were needed the most, and gave them a huge runway — 16 years to port perhaps millions of lines of code to OS X while still being able to iterate and improve without spending thousands of man-years upfront starting from scratch. Over time, of course, Carbon has improved a lot and you can mix/match Carbon & Cocoa views/code to the point where you can’t realistically tell which is which. I appreciate what a monumental effort Carbon was, from a technical standpoint. That Cocoa apps always felt 'better’ is more to Cocoa’s credit than Carbon being a bad thing — it’s a lot easier to see that in hindsight.

Final Thoughts

I am incredibly psyched about mpw. Its developer, ksherlock, has been very responsive to everything I’ve come up against as I stress test it against various tools and projects.

Right now it’s a fully usable tool that makes Classic Mac OS compilation possible and easy to do on modern versions of OS X, without requiring emulators or ancient IDEs or the like. To my knowledge, this is the first time this has been possible (excluding legacy versions of CodeWarrior).

I have used this toolset to build all kinds of things, including fun ports of my own apps. I’m sure I’ll be coming back to it for a long time to come.

I’m hoping I’m not the only person who’ll ever get to use it 🙂

Lights Off running on OS X Intel, OS X PowerPC, Mac OS 9 and System 7

Misc Gotchas

I ran into a few things along the way that are worth noting, mostly because information about them either doesn’t exist or is difficult to find on the web — check BitPaint’s makefile for context on any of these:

Pascal Strings

You want to tell clang to enable Pascal-style strings (-fpascal-strings).


If you specify -mmacosx-version-min=10.4, your Intel binary will work all the way back to 10.4, otherwise it will crash on launch trying to use invalid instructions.


Systems 1–6 support only one picture format for resources, and that’s PICTv1. Helpfully, it seems like nothing on Earth supports the creation of PICTv1 files anymore, so I wrote a very suboptimal one (but it works well):

OS X Packages

When you package a Carbon binary into a .app folder structure, as necessary for OS X, you’ll find it won’t be able to find its resource fork anymore, despite the fact that running it from the commandline will work fine. Instead, you can put the resource fork into a data file inside the bundle’s Resources folder and it will work as expected.


If you accidentally your SIZE resource, your app will launch on OS X but appear to hang, unresponsive, in the background. I ran into this more than once.


From what I can tell, including a 'carb’ resource in your binary will stop it from launching on System-7.x, but be fine on System 1–6 and 8–9.2.2. Not sure if this is an MPW problem or a me problem, but I lost quite a bit of time to “This version of MPW is not compatible with your system” alerts from my apps before realizing this.


Those who knew Classic Mac OS will be well accustomed to type/creator codes and resource forks; those who did not will be absolutely baffled by trying to figure out why they can’t open their files/disk images/binaries. I run SetFile on my disk images after creation so that DiskCopy will be able to see/open them, and I binhex encode the disk images so I can safely transfer them to a real Mac using Internet Explorer without losing the resource fork. Neither Samba (as used in VMWare’s Shared Folders) or FAT32 support resource forks, so they will get stripped and render your files unusable. SheepShaver’s external folder support does indeed support resource forks, so you’re totally fine there.


MPW includes a version of the Rez tool (which compiles your resource forks for you), but currently mpw is unable to emulate it successfully. Fortunately, Xcode still ships with Rez and today’s Rez seems almost unchanged from the version included with MPW all those years ago. Pass it the Classic Mac OS set of includes and it’s happy to spit out resource forks compatible with System 1.0.