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

Author
~~~~~~
This document was written by Francis Devereux <francis@devrx.org>

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.

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.

Building the Cocoa GUI
~~~~~~~~~~~~~~~~~~~~~~

1) Build Allegro
RPCEmu's Cocoa GUI requires a Allegro 4.4, which is still in development, or a patched version of Allegro 4.2.3.

1a) Allegro 4.2.3
Note: I have not been able to get RPCEmu to work on OS X 10.5 when it is built on OS X 10.6 with Allegro 4.2.3.  If you are building a version to release to others and you are running OS X 10.6 then you should probably use Allegro 4.4 (see 1b).

Download allegro-4.2.3.tar.gz
Untar allegro:
    tar xvzf allegro-4.2.3.tar.gz
    cd allegro-4.2.3
Patch allegro:
    patch -p1 < <path-to-rpcemu>/src/macosx/allegro-4.2.3-rpcemu.diff
    patch -p1 < <path-to-rpcemu>/src/macosx/allegro-4.2.3-uni-snowleopard.diff
If you are using Snow Leopard you also need to apply another patch:
    patch -p1 < <path-to-rpcemu>/src/macosx/allegro-4.2.3-snowleopard.diff
Configure allegro:
    chmod +x fix.sh
    ./fix.sh macosx-universal
Compile allegro
    make -j2
Install allegro
    sudo make install
    sudo make install-man
    sudo make install-framework EMBED=1

1b) Alternative: Allegro 4.4

At the time of writing Allegro 4.4's cannot be built as a universal binary, therefore if you use Allegro 4.4 you can't build a universal binary of RPCEmu (and you will have to adjust RPCEmu's Xcode project to only build for the native architecture otherwise you will get build errors).

    svn co https://alleg.svn.sourceforge.net/svnroot/alleg/allegro/branches/4.4 allegro-4.4-svn
    cd allegro-4.4-svn
    export MACOSX_DEPLOYMENT_TARGET=10.5

Build and install a non-Framework version of Allegro, necessary for #include <allegro.h> to work.
    mkdir build
    cd build
    cmake -DCMAKE_OSX_SYSROOT=/Developer/SDKs/MacOSX10.5.sdk ..
    make -j2
    sudo make install

Build and install a Framework version of Allegro, necessary for RPCEmu's Xcode build
    cd ..
    mkdir build-fw
    cd build-fw
    cmake -DCMAKE_OSX_SYSROOT=/Developer/SDKs/MacOSX10.5.sdk -DWANT_FRAMEWORKS=on ..
    make -j2
    sudo make install

2) Build RPCEmu

Open the project file in Xcode:
    cd <path-to-rpcemu>/src
    open RPCEmu.xcodeproj

If you are building on an Intel mac and have dynarec enabled (the default - to disable it remove -DDYNAREC from the "Other C Flags" build setting) then you must set the Active Build Configuration to "Release" because RPCEmu crashes on startup in the "Debug" build configuration.

Click on the "Build and Go" button.

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/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/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/startnat <network interface>
On MacBooks and MacBook Pros the wired ethernet interface is usually en0 and the wireless interface en1.

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

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.

TODO
~~~~

Keyboard:
 - make Caps Lock key work (currently pressing Caps Lock when RPCEmu has focus doesn't seem to do anything)
 - make Escape key work
 - make disabling system hot keys optional

Mouse:
 - Allow Menu and Adjust buttons to be emulated when using a trackpad (for now you'll need to use a 3 button or 2 button + wheel USB mouse)

Configuration:
 - add a GUI to configure hostfs mounts
 - make the paths of hostfs mounts relative to the RPCEmu data directory (but still allow absolute paths as well)

Cocoa GUI:
 - tick the appropriate menu item in File->CD-ROM

Network support:
 - add option to set up NAT automatically
   * probably just supply users with a script that they can run in the first release
 - automatically choose the first free tap device, instead of always opening tap0

PowerPC:
 - Display is messed up on PPC in 32 thousand colour screen modes.  May have been caused by my config.h change in 536:b8314c7278bd
 - Keys get stuck down and then keyboard becomes unresponsive

Misc:
 - see whether there's anything that depends on RPC_MACOSX being defined (not RPCEMU_MACOSX, which should still be defined)
 - full screen mode
 - stop rpclog.txt from being written inside app bundle (which should be read-only).  Put it in ~/Library/Logs instead

After each merge from upstream (svn update):
 - re-check that all calls to append_filename still use rpcemudatadir()
