QemuMac - Classic Macintosh Emulation

A collection of scripts for running classic Macintosh VMs using QEMU, supporting both 68k (Quadra 800) and PowerPC (PowerMac G4) architectures.

Requirements

• QEMU 10.x (tested with 10.0.92/v10.1.0-rc2)
• Dependencies: jq, curl, unzip
• ROM file: roms/800.ROM (for 68k VMs, auto-downloaded on first run)

Installing Dependencies

For macOS and Ubuntu/Debian Linux, you can run the dependency installer:

./install-deps.sh

This script will:

• Install required system dependencies (via Homebrew on macOS, apt on Ubuntu)
• Build the latest QEMU from source with m68k and ppc support
• Install QEMU either locally (in qemu-install/) or globally
• Verify the installation works correctly

The script supports both local installation (recommended) and global system-wide installation.

Quick Start

1. Launch a VM

For the most user-friendly experience, run the script without any arguments to open an interactive menu:

./run-mac.sh

This will show all available VMs with descriptions (e.g., "68k_quadra_800 - Mac OS 7.6.1") and guide you through selecting a VM, attaching an ISO, and choosing boot options.

Note: Multiple VMs can run simultaneously. The first VM to start gets access to the shared disk; additional VMs run without it.

2. Download Software

./iso-downloader.sh

Downloads Mac OS installers and software from curated database. Software marked with "delivery": "shared" downloads directly to the shared disk for immediate access in VMs. You need to have formatted the shared drive in an emulated machine before using this option!

Custom Software: Create iso/custom-software.json to add your own download sources. The script will automatically merge it with the default database. Use the same structure as iso/software-database.json.

3. Shared Disk for File Transfer

./mount-shared.sh        # Mount shared disk on host
./mount-shared.sh -u     # Unmount shared disk

A 512MB shared disk (HFS format) accessible by all VMs for easy file transfer between host and guests. Only one VM can access the shared disk at a time (first-come, first-served). Additional VMs can run without the shared disk.

4. Create New VM

./run-mac.sh --create-config my_mac

During VM creation, you can:

• Choose architecture (m68k Quadra 800 or PPC PowerMac G4)
• Optionally select a default installer that will be automatically downloaded and configured on first run
• Add a DESCRIPTION field to your config for easy identification in the VM menu

Usage Examples

Installing Mac OS (typical workflow)

Option 1: With Default Installer (Recommended)

The easiest way to set up a new VM - no manual downloads needed! If a VM has a DEFAULT_INSTALLER configured, the first boot automatically downloads the installer ISO and boots from it.

# 1. Create VM and select a default installer during setup (Quadra Requires Apple Legacy Software Recovery CD)
./run-mac.sh --create-config quadra_fresh

# 2. First boot auto-downloads installer ISO and boots from CD
#    Simply format the drive and install the OS - no manual downloads needed!
./run-mac.sh --config vms/quadra_fresh/quadra_fresh.conf

# 3. After installation, subsequent boots automatically use hard drive
./run-mac.sh --config vms/quadra_fresh/quadra_fresh.conf

Note: All default VMs (68k_quadra_800, power_mac_g4_os9, power_mac_g4_tiger, power_mac_g4_leopard) have DEFAULT_INSTALLER pre-configured and work this way out of the box.

Option 2: Manual Installer Setup

# 1. Create VM (skip default installer)
./run-mac.sh --create-config quadra_fresh

# 2. Boot from Apple Legacy Recovery disc, format hard drive
./run-mac.sh --config vms/quadra_fresh/quadra_fresh.conf --iso "iso/Apple Legacy Recovery.iso" --boot-from-cd

# 3. After installation, boot normally from hard drive
./run-mac.sh --config vms/quadra_fresh/quadra_fresh.conf

Mac OS X 10.5 Leopard Installation Workaround

The power_mac_g4_leopard VM requires special steps during initial setup:

# 1. First boot auto-downloads and runs Leopard installer
./run-mac.sh --config vms/power_mac_g4_leopard/power_mac_g4_leopard.conf

# 2. Let installation complete (installer will show "installation failed" - this is expected)

# 3. Choose the hard drive as startup disk

# 4. Machine will reboot from installer CD again

# 5. When language selection screen appears, close the VM window

# 6. Relaunch VM - it will now boot from hard drive automatically
./run-mac.sh --config vms/power_mac_g4_leopard/power_mac_g4_leopard.conf

# 7. Mac OS 10.5 will boot successfully

Tip: Installing Disk Copy 6.3.3 (Classic Mac OS)

For classic Mac OS systems (68k and Mac OS 9), it's recommended to copy Disk Copy 6.3.3 from the Apple Legacy Recovery disc to your hard drive. This utility is essential for mounting and creating disk images.

# 1. Boot with Apple Legacy Recovery disc mounted
./run-mac.sh --config vms/68k_quadra_800/68k_quadra_800.conf --iso "iso/Apple Legacy Recovery.iso"

# 2. In Mac OS, copy Disk Copy 6.3.3 from the CD to your hard drive

# 3. Keep it handy for working with disk images and ISOs

File Transfer Between Host and VM

# 1. Start VM and format shared disk as Mac OS Standard (HFS) if needed
./run-mac.sh --config vms/68k_quadra_800/68k_quadra_800.conf

# 2. Shutdown the VM after formatting shared disk

# 3. Mount shared disk on host (requires hfsprogs)
./mount-shared.sh

# 4. Copy files to shared mount point on host (default: /tmp/qemu-shared)
cp ~/myfiles/* /tmp/qemu-shared/

# 5. Unmount when done
./mount-shared.sh -u

Running with Software

# Boot normally with game disc mounted
./run-mac.sh --config vms/68k_quadra_800/68k_quadra_800.conf --iso iso/Marathon.iso

Default VMs

The project includes 5 pre-configured VMs ready to use:

• 68k_quadra_800 - Mac OS 7.6.1 (Quadra 800, 128M RAM, 2G disk)
• 68k_quadra_800_os753 - Mac OS 7.5.3 (Quadra 800, 128M RAM, 2G disk)
• power_mac_g4_os9 - Mac OS 9.2.2 (PowerMac G4, 512M RAM, 10G disk)
• power_mac_g4_tiger - Mac OS X Tiger 10.4 (PowerMac G4, 512M RAM, 10G disk)
• power_mac_g4_leopard - Mac OS X Leopard 10.5.6 (PowerMac G4, 512M RAM, 10G disk)

All default VMs include automatic installer setup on first boot.

Directory Structure

• vms/ - VM configurations and disk images
• iso/ - ISO files and software database
• roms/ - ROM files (800.ROM auto-downloaded for 68k VMs)
• shared/ - Shared disk accessible by all VMs (auto-created)

Features

• Concurrent VM Support: Run multiple VMs simultaneously (first-come, first-served for shared disk)
• Automatic Installers: First-run VMs auto-download and boot from installer media
• Cross-Platform: Works on macOS and Linux (Ubuntu/Debian)
• File Transfer: Shared 512MB HFS disk accessible by all VMs
• Performance Optimized: Writeback caching, authentic CPU models (m68040, G4-7400)
• User-Friendly: Interactive menus with VM descriptions for easy selection

Controls

• Linux: Right-Ctrl+G to release mouse
• macOS: Native Cocoa interface

Technical Details

• QEMU 10.x with m68k and ppc support
• Storage optimization: Writeback caching (50-80% faster), AIO threading, zero detection
• CPU models: m68040 (Quadra 800), G4-7400 (PowerMac G4)
• ROM: 800.ROM auto-downloaded for 68k VMs on first run