RPCEmu Mac OS X Information
~~~~~~~~~~~~~~~~~~~~~~~~~~~
Work is in progress to port RPCEmu to Mac OS X and build a Cocoa GUI for it.

If you have problems or need help please email the RPCEmu mailing list at RPCEmu list <rpcemu@riscos.info> and include a copy of your RPCEmu log file, ~/Library/Logs/rpclog.txt.

Contents of This File
~~~~~~~~~~~~~~~~~~~~~
This file contains information relevant to users of RPCEmu on Mac OS X.  Information for developers, including how to build from source on OS X, is in the file src/README-MacOSX within the source code. To obtain the source code install Mercurial and then execute
    hg clone http://fe4e.ath.cx/hg/rpcemu-spoon-fjd/

Author
~~~~~~
This document was written by Francis Devereux <francis@devrx.org>.  If you email me about RPCEmu please cc the mailing list, <rpcemu@riscos.info>.

Status
~~~~~~
The Cocoa GUI has been started but is not complete.
Menu entries for changing floppy and CD images should work.  Preferences should work.
Network support has been implemented, but you need to start up NAT manually.
I have only provided a dynarec (as opposed to interpreter) build so far because I don't see any reason to provide an interpreter build (dynarec is faster and I haven't experienced any problems with it that don't also exist in interpreter mode, so I thought it would be best to keep it simple and only provide one version). However if you are able to compile software you can build an interpreter version yourself (remove -DDYNAREC from the "Other C Flags" in the Project build settings in Xcode).
It is currently only possible to run RPCEmu as a 32-bit application on Mac OS X. This is because RPCEmu uses Allegro 4.4 and Allegro 4.4 for OS X uses some APIs that are not available as 64 bit (unlike Windows and Linux where Allegro 4.4 can be built as 32- or 64-bit).

How to Install
~~~~~~~~~~~~~~
I have tried to follow OS X conventions for the Mac version of RPCEmu, therefore it is supplied as an application bundle (RPCEmu.app) that can be installed in any directory, and it stores its data in your home directory.

To install, put RPCEmu.app wherever you keep your applications (e.g. /Applications) and then run it.  The first time you run it it will attempt to set up or find a data directory (which contains your hard disc files, ROM image and rpc.cfg file) and copy a ROM image into the data directory if it doesn't already contain one.

Preference Files
~~~~~~~~~~~~~~~~
The main RPCEmu settings, such as the CPU type and amount of RAM, are stored in rpc.cfg just like they are on Windows and Linux.

OS X specific settings, such as the location of your RPCEmu data directory, are stored in ~/Library/Preferences/org.devrx.RPCEmu.plist.  If you have problems setting up RPCEmu and need to start again from scratch you can delete this file and your data directory.

Usage Notes
~~~~~~~~~~~
The F15 key on an Apple keyboard is mapped to Break in RISC OS.  F15 does not exist on Apple laptop keyboards so Cmd-F12 is also mapped to Break.

The Menu and Adjust mouse buttons are not emulated with a keyboard shortcut (yet), so you'll need to use a 3-button mouse.  Note that if you have a mouse with a wheel then clicking the wheel counts as pressing the middle button (i.e. Menu in RISC OS).

Networking
~~~~~~~~~~
Networking requires TunTap for OS X which is available from http://tuntaposx.sourceforge.net/

To access the internet from your emulated RiscPC you need to enable NAT on your Mac.  An example shell script is provided, scripts/macosx/startnat.  It takes the name of the network interface you use to connect to the internet as an argument (run ifconfig to find this out).  For example, I run it like this when I'm connected to the internet using wired ethernet:
    sudo <rpcemu dir>/scripts/macosx/startnat en0

To get networking going you need to do the following:

1. tap kext
If you did not install the TunTap Startup Item when you installed TunTap then you need to load the tap kext:
    sudo kextload /Library/Extensions/tap.kext

2. NAT
Start NAT with the startnat script provided (or some other way if you prefer):
    sudo <rpcemu dir>/scripts/macosx/startnat <network interface>
On MacBooks and MacBook Pros the wired ethernet interface is usually en0 and the wireless interface en1.

Note: instead of loading tap.kext and running startnat separately you can use the startrpcemunet script to do both in one go.

3. Start RPCEmu
Start RPCEmu.  Enter your password when prompted (admin privileges are required to install the privileged helper tool that starts the tap interface for RPCEmu).

N.B. if networking fails to start because you forgot to load tap.kext before you started RPCEmu then you must run:
    sudo launchctl unload -w /Library/LaunchDaemons/org.devrx.RPCEmu.plist
in Terminal before restarting RPCEmu in order to get networking to work.

4. RPCEmu configuration
Open the RPCEmu preferences window (RPCEmu->Preferences) and check that the IP Address is set to 172.31.0.1.  If not change it and restart RPCEmu.

5. RISC OS configuration
Follow the RISC OS parts of http://www.riscos.info/index.php/RPCEmu_Linux_Guide#Network_support to configure the emulated operating system.  Please ignore the parts of the guide that refer to the Linux host.
