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 https://github.com/jjuran/metamage_1 cd metamage_1
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.12 (including PPC and x86). The front end requires 32-bit support and definitely doesn’t build on 10.14.
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 can run this under
but really you should just join
video. Otherwise, every process belonging
to Advanced Mac Substitute runs 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: