Advanced Mac Substitute HOWTO

Welcome to Advanced Mac Substitute, an API-level reimplementation of classic Mac OS.

Advanced Mac Substitute is a factored application. The backend includes a 68K emulator, a file server, and other utilities (which should build and run on any POSIX-like system), as well as implementions of Mac OS system calls compiled to 68K machine code. The frontend is a generic bitmapped terminal abstraction which has been ported to four platforms so far: classic Mac OS, Mac OS X (10.4 through 10.13, at least), Linux framebuffer, and Android.

To run Advanced Mac Substitute, you need a supported front end, the back end (including both native and emulated parts), and a Mac application (emulated, of course).

The emulated programs (including a few sample applications) are available as prebuilt binaries, and will be fetched automatically by the build recipes below. The remaining pieces must be built from source.


Source code for Advanced Mac Substitute is on GitHub.

git clone
cd metamage_1

VNC (Virtual Network Computing)

If none of the options below are available, you can use VNC as the front end:

make ams-vnc

This will build the necessary programs and launch a VNC server listening to port 5900 on localhost. It uses 8-bit true-color graphics (grayscale), which is known to work with the Chicken VNC client on OS X.

Mac OS X

If you’re running Mac OS X, run

make ams-osx

This will

It’s been tested on most versions of Mac OS X between 10.4 and 10.14 (including PPC and x86). The front end requires 32-bit support. On 10.14, it can’t be built with Apple’s dev tools, but will build and run with homebrew. (Another option is to use VNC, above.)

X Window System

If you have an X11 environment, run

make ams-x11

It’s been tested with X.Org/Linux. It might even work on non-Linux systems if they have process-shared condvars. It doesn’t work completely in XQuartz or, but patches are welcome.

If you have a non-Mac keyboard, I recommend setting INTERACT_SWAP_CMD_OPT=1.

Linux framebuffer

If you’re running a Linux distribution, switch to virtual console 1. (You need to have framebuffer access — a VPS in the cloud isn’t going to work.) You’ll need some build tools installed. On Debian, at least:

apt-get install git make g++ libssl-dev

All of the following commands may be run either from the console or a remote shell.

Privileges are required for certain operations (root suffices in all cases):

If the console is already in graphics mode, then root isn’t needed, and you merely need to be a member of groups video, input, and tty (unless you’re running an old kernel in which group tty can’t open /dev/tty0). Even if root is required, Advanced Mac Substitute will attempt to minimize its use of it, by separating and dropping privileges where possible. This may involve running programs under sudo, in which case the calling program must know the exact pathname of the privileged program, since sudo doesn’t search the caller’s PATH. For this reason, you’ll need to choose an installation path prefix, e.g.


Use $HOME as the install prefix if you lack root access (but remember, you must be a member of each group mentioned and the console must already be in graphics mode). The default (if you just run ./configure) is /usr/local.

After running ./configure, run

make ams-linux

The built programs will be copied to var/out (relative to metamage_1). To install the privileged ones, run

sudo make ams-linux-inst

(You can omit sudo if you’re installing to $HOME.)

I’ve found that sudo -n true takes about 150ms on a Raspberry Pi 1. To avoid that overhead, make sure you’re a member of group input and run

sudo make ams-linux-suid

to set the privileged program kdmode setuid-root — the calling program will check the setuid bit and ownership at run time and omit the sudo invocations.

Finally, run

make ams-linux-demo

If you’re not a member of group video, you’ll need to add yourself to it. Don’t run Advanced Mac Substitute as root.

The demo runs the Welcome application.


To dismiss the Welcome application, click anywhere on the emulated screen. (Pressing any key also works, if the front end supports key events — which is true in OS X and not in Linux (yet).) You can also press Ctrl-C from the terminal which launched the demo (even if that’s the same Linux console the demo is running on).

To try another application, set AMS_APPNAME to its name:


These applications are included with Advanced Mac Substitute:

Configuring the Keyboard in Linux

To use a keyboard with Advanced Mac Substitute in Linux, you need to identify the corresponding eventX file in /dev/input:

grep sysrq /proc/bus/input/devices

On my Raspberry Pi, I get

H: Handles=sysrq kbd event0

Using this example, run


WARNING: This will "grab" the keyboard, making it unavailable to the terminal, so Ctrl-C won’t work. Make sure you can log in with a remote shell (in case you’re not already) in the event that something goes wrong and you need to run killall display. As long as the Advanced Mac Substitute operating system is still working, though, you can kill it immediately by pressing Command-Option-Esc.

If you’re using a non-Mac keyboard (with Alt next to the space bar), I recommend also setting INTERACT_SWAP_CMD_OPT=1 to map Command to Alt and Option to the key with the OS logo.

Using a Disk Image

You can also launch an application from an MFS disk image. For example:

curl -LO
mv Lode_Runner.dsk ../ams-68k-bin/mnt/
AMS_DISK=Lode_Runner.dsk AMS_APPNAME="Lode Runner" make ams-osx

Playing Sound

You may optionally use a sound server with Advanced Mac Substitute. One is provided, called sndtrack. It requires PortAudio, which you should install using your operating system’s built-in package system if it has one. For example:

sudo apt-get install portaudio19-dev

If PortAudio development files aren’t installed, a PortAudio mirror will be cloned and built instead (which is known to work in Mac OS X).

make sndtrack

Once sndtrack is built, sound should be available in Advanced Mac Substitute. So far, it’s known to work in several GNU/Linux configurations (including both in and out of X11, and with and without PulseAudio), and in certain versions of OS X ranging from 10.4 to 10.12.

A good first test of sound support is Tic-tac-toe. A really good example of playing sounds is Lode Runner.

If everything works but you’re getting a spew of irrelevant diagnostic messages from ALSA, set SNDTRACK_SUPPRESS_ALSA_ERRORS=1 in the environment.