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.12, 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

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.12 (including PPC and x86). The front end requires 32-bit support and definitely doesn’t build on 10.14.

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 can run this under sudo, but really you should just join video. Otherwise, every process belonging to Advanced Mac Substitute runs 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: