Bash toolkit for classic Mac emulation via QEMU - Pre-configured VMs for Quadra 800 (68K) and PowerMac G4 (PPC) running Mac OS 7.5-9.2 and OS X Tiger/Leopard
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.
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.
When working with this QemuMac repository, follow these guidelines:
First, familiarize yourself with the two supported architectures:
**m68k Architecture (Macintosh Quadra 800):**
**PPC Architecture (PowerMac G4):**
**To launch VMs:**
```bash
./launch.sh
./run-mac.sh --config vms/power_mac_g4_os9/config.sh
./run-mac.sh --config vms/68k_quadra_800/config.sh --iso iso/some-software.iso
./run-mac.sh --config vms/power_mac_g4_tiger/config.sh --iso iso/installer.iso --boot-from-cd
```
**To create new VMs:**
```bash
./run-mac.sh --create-config my_new_vm
```
**Default VMs available:**
When creating or modifying VM configs (located in `vms/<vm_name>/config.sh`):
```bash
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"
PRAM_FILE="vms/my_vm/pram.bin"
SCSI_ID=0 # Boot disk SCSI ID
SHARED_SCSI_ID=4 # Shared disk SCSI ID
DEFAULT_INSTALLER="macos922" # Auto-setup on first boot
```
**Download operating systems and software:**
```bash
./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"
}
}
```
**Mount shared disk on host:**
```bash
./mount-shared.sh
cp myfile.sit /tmp/qemu-shared/
./mount-shared.sh -u
```
**Shared disk details:**
**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:**
The toolkit automatically applies these optimizations:
**Storage I/O:**
**CPU Models:**
**m68k (SCSI-based):**
**PPC (IDE-based):**
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.
**Create a new PowerPC VM with Tiger:**
```bash
./run-mac.sh --create-config my_tiger_vm
```
**Add software to shared disk:**
```bash
./iso-downloader.sh
```
**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
```
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)
**VM won't boot:**
**Shared disk not accessible:**
**Performance issues:**
**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.
Leave a review
No reviews yet. Be the first to review this skill!
# Download SKILL.md from killerskills.ai/api/skills/qemumac-classic-emulation/raw