Apple3rtr on macOS, Ubuntu and Raspbian

Apple3rtr is the quickest path to set up an Apple III emulator on modern platforms.  The Drop /// Inches podcast discusses details about apple3rtr and other Apple III-related topics.

In some platforms, however, it is a bit tricky to install the prerequisite software (MAME, SDL, etc.) properly.  This article describes the steps to install apple3rtr on the following platforms:

1. apple3rtr on macOS Mojave 10.14.6
2. apple3rtr on Ubuntu 18.04.3 LTS
3. apple3rtr on Raspbian Buster

Note: Info on this page was verified as of October 2019.

1. Apple3rtr on macOS Mojave 10.14.6

It is a straightforward task to set up apple3rtr on macOS.  The step-by-step instruction is found in apple3rtr Readme (see "SDL and MAME Installation").

a. Install MAME0214

Download SDLMAME v0.214 64-bit.zip from http://sdlmame.lngn.net/. 

Unzip the file and install the binary:

unzip mame0214-64bit.zip
cd mame0214-64bit
sudo cp mame64 /usr/local/bin
sudo chmod +x /usr/local/bin/mame64

b. Install SDL2

Download SDL2-2.0.10.dmg (or the latest dmg) from http://www.libsdl.org/download-2.0.php. 

Then run:

open SDL2-2.0.10.dmg
sudo cp -r /Volumes/SDL2/SDL2.framework /Library/Frameworks

You may be required the admin password.

c. Clone apple3rtr repository

git clone https://github.com/datajerk/apple3rtr

d. Start MAME + apple3rtr

cd apple3rtr
mame64 apple3 -window -skip_gameinfo -volume -24 -resolution 1024x768 -effect Scanlines0x4 -sl1 cffa2 -hard apple3.hd -sl2 thclock -sl3 applicard -ramsize 512k -flop1 demodisk.dsk

The option -flop1 specifies the boot floppy image.  Apple3rtr includes several boot images.  To quit apple3rtr, press F1 and then Esc.

2. Apple3rtr on Ubuntu 18.04.3 LTS

On Ubuntu, you need to build MAME from the source code, as the MAME from apt package doesn't seem to work with apple3rtr.

a. Install prerequisite packages

sudo apt-get update
sudo apt-get install git build-essential python libsdl2-dev libsdl2-ttf-dev libfontconfig-dev qt5-default

b. Download MAME 0214 source

mkdir mame0214; cd mame0214
wget https://github.com/mamedev/mame/releases/download/mame0214/mame0214s.zip
unzip mame0214s.zip
unzip mame.zip 

c. Build MAME 0214

make NOWERROR=1 REGENIE=1 -j3

When done, install mame64:

sudo cp mame64 /usr/local/bin/
sudo chmod +x /usr/local/bin/mame64

d. Clone apple3rtr repository

git clone https://github.com/datajerk/apple3rtr

e. Start MAME + apple3rtr

cd apple3rtr
mame64 apple3 -window -skip_gameinfo -volume -24 -resolution 1024x768 -effect Scanlines0x4 -sl1 cffa2 -hard apple3.hd -sl2 thclock -sl3 applicard -ramsize 512k -flop1 demodisk.dsk

The option -flop1 specifies the boot floppy image.  Apple3rtr includes several boot images.  To quit apple3rtr, press F1 and then press Esc.

3. Apple3rtr on Raspbian Buster

At least a Raspberry Pi 3b+ is required to build MAME from the source.  Raspbian Buster, Kernel 4.19, Sep. 2019 or newer is recommended.

The latest MAME as of Sep. 2019, MAME 0214, somehow did not work with apple3rtr.  I rolled back to MAME 0187 for a successful build. 

Due to the RAM size and other resource limitations in the system, a couple of additional steps are required:

1. Use SOURCES make parameter to limit the number of files to compile.

2. Temporarily increase the swap space.

Detailed steps are described below.

a. Prepare Raspbian system SD memory card

Download the system image from the Raspberry Pi download page.  As of September 2019, Raspbian Buster kernel 4.19 is the latest.  A 32GB SD card is recommended.  You can use etcher tool to write the image on your SD card. 

b. Configure Raspberry Pi environment

Some additional configuration of the Raspberry Pi will be useful for build of MAME.  You may want to:

• Enable Wifi, ssh and vnc
• Setup keyboard locale
• Boot in console

These tasks can be done using raspi-config. 

c. Install prerequisite packages

sudo apt-get update
sudo apt-get install git build-essential python libsdl2-dev libsdl2-ttf-dev libfontconfig-dev qt5-default

d. Download and unzip MAME0187 source tree

mkdir mame0187; cd mame0187
wget https://github.com/mamedev/mame/releases/download/mame0187/mame0187s.zip
unzip mame0187s.zip
unzip mame.zip

e. Build MAME0187

Before building MAME, increase the swap size temporarily.  Edit the swap configuration file:

sudo vi /etc/dphys-swapfile

And modify this line:

CONF_SWAPSIZE=100

to:

CONF_SWAPSIZE=2048

then save the file and restart Raspberry Pi.  After restart, use free command to verify that the swap size is increased:

pi@raspberrypi3:~ $ free -m
               total        used        free      shared  buff/cache   available
Mem:            926         167         461          14         296         691
Swap:          2047           0        2047

Now you can build MAME:

cd mame0187
make NOWERROR=1 SUBTARGET=apple3 SOURCES=src/mame/drivers/apple3.cpp,src/mame/machine/apple3.cpp -j2

If you previously ran the make command with different options, add the option REGENIE=1 as well.

It will take about two to four hours for the command to finish.  After the command is done, verify that the binary file named apple3 is created.  Install it:

sudo cp apple3 /usr/local/bin/
sudo chmod +x /usr/local/bin/apple3

Now the build is done, set the swap size back to the original.  Edit CONF_SWAPSIZE value in /etc/dephys-swapfile:

CONF_SWAPSIZE=100

Save file, quit editor, and restart Raspberry Pi.

f. Clone apple3rtr repository

git clone https://github.com/datajerk/apple3rtr

g. Start MAME + apple3rtr

cd apple3rtr
apple3 apple3 -skip_gameinfo -nowindow -volume -24 -resolution 512x384 -sl1 cffa2 -hard apple3.hd -sl2 thclock -sl3 applicard -ramsize 512k -flop1 demodisk.dsk

The option -flop1 specifies the boot floppy image.  Apple3rtr includes several boot images.  To quit apple3rtr, press F1 and then Esc.

4. Programming in Apple III Business Basic

1. Boot apple3rtr with bosboot.dsk
2. From BOS main menu choose Business Basic
3. Try this code (mandelbrota3.ba3)

Reference: Apple III Business BASIC Reference Manual Vol 2