Advanced Mac Substitute HOWTO

https://www.v68k.org/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 for displaying graphics and receiving user input. Officially supported front ends include macOS / OS X (at least 10.4 through 10.15 and 11), Linux framebuffer, X11, and VNC. (Though originally developed in classic Mac OS, that’s no longer supported.)

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.

Building

Source code for Advanced Mac Substitute is on GitHub.

git clone https://github.com/jjuran/metamage_1
cd metamage_1

Each of the options below will

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

The VNC server 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 macOS / OS X, run

make ams-quartz-demo

This will

Open an application bundle to launch the application in the emulator. In fullscreen mode, Command-Option-Esc will kill the entire application immediately. (You may need to use this the first time you Open or Save in Tic-tac-toe, in macOS 10.15 or later.)

It’s been tested on most versions of Mac OS X / OS X / macOS between 10.2 and 11 (including PPC, x86, and ARM). Audio support requires 10.4 or later. Using MacRelix.app as a front end is deprecated, unless you know what you’re doing.

(WARNING: Do not launch these applications when multiple users are logged into the console in OS X 10.9 or 10.10!

These applications call CGDisplayCapture() to capture the screen. If you run one in OS X 10.9 or 10.10 with multiple users logged into the console, the subsequent CGDisplayRelease() call on exit will hang, and you’ll have to reboot.)

X Window System

If you have an X11 environment, run

make ams-x11

This will

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 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++

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.

INSTALL_PREFIX=/usr/local ./configure

The default (if you just run ./configure) is ~/.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

make ams-linux-inst

(Make sure to use sudo if you’re installing to /usr/local.)

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.

Welcome

A parody of the Macintosh loading screen.
Welcome to Advanced Mac Substitute.
(This is an application, not a real loading screen.)

To dismiss the Welcome application, click anywhere on the emulated screen or press any key.

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 /dev/input:

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 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 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

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 at least 10.15.

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.

Installation

Once you’ve verified that Advanced Mac Substitute works, you’ll probably want to have it properly installed. Run one of the following:

make ams-x11-install    # X Window System
make ams-linux-install  # Linux framebuffer and /dev/input
make ams-vnc-install    # Custom VNC server

(Installation in macOS / OS X is no longer necessary.)

Then make sure that <install-prefix>/bin is in your PATH, and run ams. To run a different application, you can pass its name as an argument, e.g.:

ams "Nyanochrome Cat"