Retro68

A GCC-based cross-compilation environment for 68K and PowerPC Macs. Why? Because there is no decent C++17 Compiler targeting Apple's System 6. If that's not a sufficient reason for you, I'm sure you will find something more useful elsewhere.

If you are crazy enough to try it out, please say hello at wolfgang.thaller@gmx.net.

Installing/Building

The Retro68 git repository uses submodules; be sure to use the --recursive option to git clone or use

git submodule update --init

after cloning. To get the latest changes, use

git pull
git submodule update

Note: There is now experimental support for the Nix Package Manager. If you're a nix user, skip ahead to the Using Retro68 with Nix section.

Prerequisites

• Linux, Mac OS X or Windows (via Cygwin)
• boost
• CMake 3.9 or later
• GCC dependencies: GMP 4.2+, MPFR 2.3.1+ and MPC 0.8.0+
• bison version 3.0.2 or later
• ruby version 2.1 or later
• flex
• texinfo
• Recommended: Apple Universal Interfaces (version 3.x; version 3.4 is tested)
• An ancient Mac and/or an emulator.

For Ubuntu Linux, the following should help a bit:

sudo apt-get install cmake libgmp-dev libmpfr-dev libmpc-dev libboost-all-dev bison flex texinfo ruby

For Arch Linux, this should do the trick:

sudo pacman -S --needed cmake gmp mpfr libmpc boost bison flex texinfo ruby

On a Mac, get the homebrew package manager and:

brew install boost cmake gmp mpfr libmpc bison texinfo

You can also run Retro68 on a PowerMac G4 or G5 running Mac OS 10.4 (Tiger). In that case, get the tigerbrew package manager and

brew install gcc cmake gmp mpfr libmpc bison texinfo
brew install boost --c++11

Apple Universal Interfaces vs. Multiversal Interfaces

To compile code for the Mac, you need header files and libraries describing the APIs. There are two choices: Apple's Universal Interfaces, or the brand-new open source reimplementation, the Multiversal Interfaces.

The Multiversal Interfaces are included with Retro68 out of the box, and they are free software. However, they are incomplete and may still contain serious bugs. Missing things include Carbon, MacTCP, OpenTransport, Navigation Services, and basically everything introduced after System 7.0.

The Universal Interfaces used to be a free download from Apple. However, they have taken the site off-line and the license agreement does not allow redistribution, which is why it's not included in this repository. The concept of fair use might cover keeping it available for reasons of historical interest, or it might not. I am not a lawyer.

If you find a copy of Apple's Universal Interfaces, you can put it inside the InterfacesAndLibraries directory in the source tree, and Version 3.4 has received the most testing, but any 3.x version could theoretically work. The exact directory layout inside the InterfacesAndLibraries directory does not matter. It will be picked up automatically when Retro68 is built.

Especially on non-macOS platforms, make sure that the Mac resource fork of the PowerPC library files is included in a format recognized by Retro68. Recognized formats include MacBinary II (e.g., Interfacelib.bin), AppleDouble (._InterfaceLib or %InterfaceLib) or Basilisk/Sheepshaver resource forks (.rsrc/InterfaceLib).

The Universal Interfaces were also included with Apple's free-to-download Macintosh Programmer's Workshop (MPW; redistribution is not officially allowed, either) and with Metrowerks CodeWarrior.

One of the most easily found downloads is the MPW 3.5 Golden Master release, usually in a file named MPW-GM.img.bin or mpw-gm.img_.bin. At the time of this writing, this can be found at:

http://macintoshgarden.org/apps/macintosh-programmers-workshop
https://www.macintoshrepository.org/1360-macintosh-programmer-s-workshop-mpw-3-0-to-3-5
https://staticky.com/mirrors/ftp.apple.com/developer/Tool_Chest/Core_Mac_OS_Tools/MPW_etc./MPW-GM_Images/MPW-GM.img.bin

You will need a Mac or a Mac emulator (with DiscCopy) to read that file.

Windows Compilation using Cygwin

You can compile Retro68 on Windows using via a Cygwin terminal. When installing Cygwin, select the following packages in the Cygwin Setup program (as per the dependencies listed above):

• bison
• cmake
• flex
• gcc-core
• gcc-g++
• libboost-devel
• libgmp-devel
• libmpc-devel
• libmpfr-devel
• make
• texinfo
• zlib-devel

Additional dependencies will be automatically installed.

Note that compilation via Cygwin is around 3X slower than other platforms.

Compiling Retro68

Once you have all the prerequisites, execute these commands from the top level of the Retro68 directory:

mkdir ../Retro68-build
cd ../Retro68-build
../Retro68/build-toolchain.bash

The toolchain will be installed in the "toolchain" directory inside the build directory. All the commands are in toolchain/bin, so you might want to add that to your PATH.

If you're building this on a PowerMac running Mac OS X 10.4, tell the build script to use the gcc you've installed via tigerbrew:

../Retro68/build-toolchain.bash --host-cxx-compiler=g++-7 --host-c-compiler=gcc-7

Build options and recompiling

Building all of Retro68 involves building binutils and gcc... twice, so it takes quite a while.

You can pass the --no-68k, --no-ppc or --no-carbon flags to build-toolchain to limit yourself to the old Macs you're really interested in (note that --no-ppc implies --no-carbon).

After the initial build, you can use the --skip-thirdparty option in order to skip gcc and binutils and just compile the Retro68-specific tools, libraries and sample programs. The build-host, build-target, build-target-ppc and build-target-carbon directories are CMake build directories generated from the top-level CMakeLists.txt, so you can also cd to one of these and run make separately if you've made changes.

Using Retro68 with Nix

If you are not using the Nix Package Manager, please skip this section. But maybe you should be using it ;-).

Nix is a package manager that runs on Linux and macOS, and NixOS is a Linux distribution based on it. Try the Determinate Nix Installer for the best installation experience.

[TODO: docs on using the binary cache to avoid builds]

Once you've got nix installed, and without checking out the Retro68 repository, you can run

nix develop github:autc04/Retro68#m68k

from the Retro68 directory to get a shell with the compiler tools targeting 68K Macs available in the path, and CC and other environment variables already set up for you. You can then cd to one of the example directories or to your own project and use cmake to build it.

Likewise, use

nix develop github:autc04/Retro68#powerpc

... to get an environment targeting PowerPC Macs.

If you have a local checkout of Retro68, you can replace github:autc04/Retro68 by the path to that local checkout, e.g., run nix develop .#m68k from inside the Retro68 directory.

To see how to set up your own nix-based build and development environment for your own application, head over to the github.com/autc04/Retro68NixSample repository.

You can also use the nix build command to build packages. As always with nix, the result will be somewhere in a subdirectory of /nix/store, with a symlink named result placed in the directory where you invoked the command.

| Command | What | |--------------------------------------------------------------------|-------------------------------------------| | nix build github:autc04/Retro68#samples-m68k | Sample programs for 68K | | nix build github:autc04/Retro68#samples-powerpc | Sample programs for PowerPC | | nix build github:autc04/Retro68#pkgsCross.m68k.zlib | zlib library, cross-compiled for 68K Macs | | nix build github:autc04/Retro68#pkgsCross.m68k.packagename | cross-compile packagename to 68K | | nix build github:autc04/Retro68#pkgsCross.powerpc.packagename | cross-compile packagename to PowerPC |

You can attempt to cross-compile any package from the nixpkgs collection. Unless the package contains a very portable library, the command will of course fail. Please don't report bugs, please report successes instead!

Using Retro68 with Docker

Whenever commits are merged into the Retro68 git repository, a build pipeline is triggered to create a container image which is then pushed to the Retro68 package repository as ghcr.io/autc04/retro68. This image contains the complete 68K and PPC toolchains ready for use for either local development or as part of CI pipeline. The command line below shows an example invocation of Retro68 to build the Samples/Raytracer app:

$ git clone --depth 1 https://github.com/autc04/Retro68.git
$ cd Retro68
$ docker run --rm -v $(pwd):/root -i ghcr.io/autc04/retro68 /bin/bash <<"EOF"
    cd Samples/Raytracer
    rm -rf build && mkdir build && cd build
    cmake .. -DCMAKE_TOOLCHAIN_FILE=/Retro68-build/toolchain/m68k-apple-macos/cmake/retro68.toolchain.cmake
    make
EOF

The container image is configured by default to use the multiversal interfaces, but it is possible to use the universal interfaces by passing a path to either a local file or a URL that points to a Macbinary DiskCopy image containing the "Interfaces&Libraries" directory from MPW.

Using the universal interfaces from a local file:

$ docker run --rm -v $(pwd):/root -v $(pwd)/MPW-GM.img.bin:/tmp/MPW-GM.img.bin \
  -e INTERFACES=universal -e INTERFACESFILE=/tmp/MPW-GM.img.bin \
  -i ghcr.io/autc04/retro68 /bin/bash <<"EOF"
    cd Samples/Raytracer
    rm -rf build && mkdir build && cd buil