QemuMac Classic Emulation

A comprehensive QEMU-based classic Macintosh emulation environment supporting both m68k (Quadra 800) and PowerPC (PowerMac G4) architectures. Provides pre-configured VMs, automatic ROM/installer setup, and a shared disk system for file transfer.

Overview

This toolkit enables running classic Mac OS versions (7.5-9.2) and Mac OS X (Tiger/Leopard) using QEMU virtualization. It includes interactive launchers, software management, and optimized performance configurations.

Instructions for AI Agent

When working with this QemuMac repository, follow these guidelines:

1. Understanding the Architecture

First, familiarize yourself with the two supported architectures:

**m68k Architecture (Macintosh Quadra 800):**

**PPC Architecture (PowerMac G4):**

2. Working with VMs

**To launch VMs:**

```bash

Interactive menu-driven launcher

./launch.sh

Launch specific VM

./run-mac.sh --config vms/power_mac_g4_os9/config.sh

Launch with ISO attached

./run-mac.sh --config vms/68k_quadra_800/config.sh --iso iso/some-software.iso

Boot from CD/ISO

./run-mac.sh --config vms/power_mac_g4_tiger/config.sh --iso iso/installer.iso --boot-from-cd

```

**To create new VMs:**

```bash

Interactive VM creation with optional default installer

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

```

**Default VMs available:**

3. VM Configuration Format

When creating or modifying VM configs (located in `vms/<vm_name>/config.sh`):

```bash

Required variables

ARCH="m68k" # or "ppc"

MACHINE_TYPE="q800" # or "mac99"

RAM_SIZE="128M"

HD_SIZE="2G" # for new VMs

HD_IMAGE="vms/my_vm/hd.img"

m68k-specific

PRAM_FILE="vms/my_vm/pram.bin"

SCSI_ID=0 # Boot disk SCSI ID

SHARED_SCSI_ID=4 # Shared disk SCSI ID

Optional

DEFAULT_INSTALLER="macos922" # Auto-setup on first boot

```

4. Software Management

**Download operating systems and software:**

```bash

Interactive downloader

./iso-downloader.sh

```

**Software database:**

**To add custom software**, edit `iso/custom-software.json`:

```json

{

"custom_app": {

"name": "My Application",

"url": "https://example.com/app.sit",

"sha256": "...",

"category": "Applications",

"architectures": ["ppc", "m68k"],

"delivery": "shared"

}

}

```

5. File Transfer System

**Mount shared disk on host:**

```bash

Mount at /tmp/qemu-shared

./mount-shared.sh

Copy files

cp myfile.sit /tmp/qemu-shared/

Unmount

./mount-shared.sh -u

```

**Shared disk details:**

6. Dependencies

**Check and install required tools:**

Ubuntu/Debian:

```bash

sudo apt-get install qemu-system-m68k qemu-system-ppc qemu-utils jq curl unzip hfsprogs

```

macOS:

```bash

brew install qemu jq hfsutils

```

**Required tools:**

7. Performance Optimizations

The toolkit automatically applies these optimizations:

**Storage I/O:**

**CPU Models:**

8. Boot Device Handling

**m68k (SCSI-based):**

**PPC (IDE-based):**

9. First-Run Installer System

VMs with `DEFAULT_INSTALLER` automatically:

1. Download required installer ISO on first run

2. Boot from installer

3. Subsequent boots use hard drive

**Architecture filtering:** Only compatible installers offered during VM creation.

10. Common Tasks

**Create a new PowerPC VM with Tiger:**

```bash

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

Select PPC architecture

Choose Tiger installer from menu

```

**Add software to shared disk:**

```bash

./iso-downloader.sh

Select software with "shared" delivery

Files appear directly in shared disk

```

**Boot existing VM from recovery CD:**

```bash

./run-mac.sh --config vms/68k_quadra_800/config.sh --iso iso/recovery.iso --boot-from-cd

```

**Transfer files from host to VM:**

```bash

./mount-shared.sh

cp ~/myfiles/* /tmp/qemu-shared/

./mount-shared.sh -u

Launch VM, access shared disk

```

11. Key Files and Directories

12. Best Practices

1. **Always read VM config** before modifying launch parameters

2. **Use `./launch.sh`** for interactive exploration

3. **Test ROM auto-download** for m68k VMs on first run

4. **Format shared disk** as HFS from within Mac OS after first creation

5. **Check architectures** in software database when adding new software

6. **Use `--boot-from-cd`** for recovery or installation scenarios

7. **Avoid multi-threaded TCG** (compatibility issues with m68k/PPC)

13. Troubleshooting

**VM won't boot:**

**Shared disk not accessible:**

**Performance issues:**

14. Advanced Usage

**Manual QEMU parameters:**

Modify `run-mac.sh` function `build_qemu_args()` for architecture-specific customization.

**Custom ROM files:**

Place in `roms/` directory with appropriate naming.

**Networking:**

Currently not configured by default - can be added via QEMU network parameters in VM config.

Notes