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 https://github.com/jjuran/metamage_1 cd metamage_1
VNC (Virtual Network Computing)
If none of the options below are available, you can use VNC as the front end:
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
- build the following:
- tools required for building applications
- MacRelix.app, a user interaction server used as the front end
- tools required for the Advanced Mac Substitute back end
- launch MacRelix.app
- run the Welcome application
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
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 X11.app, but patches are welcome.
If you have a non-Mac keyboard, I recommend setting
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):
root, for switching the console between text mode and graphics mode
tty, for querying the console mode (in case switching isn’t needed)
input, for reading
video, for accessing
If the console is already in graphics mode, then
root isn’t needed,
and you merely need to be a member of groups
(unless you’re running an old kernel in which group
tty can’t open
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,
sudo doesn’t search the caller’s
For this reason, you’ll need to choose an installation path prefix, e.g.
$HOME as the install prefix if you lack
(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
The built programs will be copied to
var/out (relative to
To install the privileged ones, run
sudo make ams-linux-inst
(You can omit
sudo if you’re installing to
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
If you’re not a member of group
video, you’ll need to add yourself to it.
Don’t run Advanced Mac Substitute as
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:
AMS_APPNAME=Tic-tac-toe export AMS_APPNAME
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
grep sysrq /proc/bus/input/devices
On my Raspberry Pi, I get
H: Handles=sysrq kbd event0
Using this example, run
INTERACT_KEYBOARD=/dev/input/event0 export INTERACT_KEYBOARD
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
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
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 https://archive.org/download/mac_Lode_Runner/Lode_Runner.dsk mv Lode_Runner.dsk ../ams-68k-bin/mnt/ AMS_DISK=Lode_Runner.dsk AMS_APPNAME="Lode Runner" make ams-osx
You may optionally use a sound server with Advanced Mac Substitute.
One is provided, called
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).
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,
SNDTRACK_SUPPRESS_ALSA_ERRORS=1 in the environment.