⚠️ PROOF OF CONCEPT - This is an experimental, educational reimplementation of Apple's Macintosh System 7. This is NOT a finished product and should not be considered production-ready software.
"I've finally done it. I have discovered the world's most cursed operating system. It's more cursed than ReactOS. It's more cursed than Hannah Montana Linux."
"This is literally the AI sloperating system."
"No freaking way. This abomination is booting."
"It works at all is just absolutely insane."
— Action Retro, installing it on a Pentium 3, a ThinkPad X1 Carbon, and an 11" Intel MacBook Air
An open-source reimplementation of Apple Macintosh System 7 for modern x86 hardware, bootable via GRUB2/Multiboot2. This project aims to recreate the classic Mac OS experience while documenting the System 7 architecture through reverse engineering analysis.
New here? Start with Getting Started | All docs? See Documentation Index | History? Read the Project Evolution retrospective | Contribute? See Contributing
Using Claude Code? See CLAUDE.md for project-specific guidance
This began as an AI-assisted reverse-engineering research project, published to Zenodo in 2025, and has grown into a bootable System 7 reimplementation. The project remains experimental: its x86 target boots in QEMU and has been verified on one physical UEFI ThinkPad, while broad hardware compatibility and real-application compatibility are still unverified.
The Action Retro video below captured an earlier revision that froze on the tested machines. Subsequent work fixed the reported boot, interrupt, and input problems; the historical findings and fixes are summarized below. QEMU coverage is substantially broader than bare-metal testing, and individual subsystems still have documented compatibility gaps.
For the project's history, see the Project Evolution retrospective. For current limitations, see Known Issues and Compatibility Gaps.
In the video, he booted an earlier revision on a Pentium 3, a ThinkPad X1 Carbon, and an 11" Intel MacBook Air. That revision froze, had non-working mouse input, and had a confusing GRUB boot flow. Investigating those reports identified several bare-metal bugs:
| What he saw | What was actually wrong | Status |
|---|---|---|
| "We've got the same goofy grub issue" | set timeout=-1 — GRUB waited forever for a keypress, so headless/serial-only machines never booted the kernel at all |
✅ Fixed |
| Froze right after the desktop appeared | No GDT was ever installed. Multiboot2 leaves GDTR undefined; the kernel borrowed GRUB's temporary GDT and later allocated over it. The first interrupt then resolved a dead selector → #GP → #DF → silent triple-fault reset | ✅ Fixed |
| Froze with no explanation | CPU exception vectors all pointed at a bare iret, so any fault reset the machine with zero diagnostics. Now prints the fault name, eip, error code and cr2 |
✅ Fixed |
| "Mouse does nothing" | IRQ2 (the slave-PIC cascade) was never unmasked — so IRQ12 could never reach the CPU no matter what. IRQ0 was never unmasked either, so the timer never ticked | ✅ Fixed |
| Hung before printing anything | serial_putchar spun forever waiting on the UART, deadlocking the boot on machines whose port never reports ready |
✅ Fixed |
| Wouldn't start on a modern ThinkPad at all | The ISO was built BIOS-only (grub-mkrescue -d i386-pc) — one El Torito entry, no EFI payload. On UEFI-only machines there was nothing for the firmware to execute |
✅ Fixed |
Confirmed on a physical ThinkPad booting via UEFI — not an emulator. Every machine in the video froze; this one doesn't. The missing GDT was the real culprit behind the freezes, and the BIOS-only ISO was why newer machines wouldn't start at all.
The CI workflow boots headless QEMU through both firmware paths and requires the kernel to reach its event loop, emit a timer heartbeat, and avoid logging a CPU exception:
| Firmware | CI assertion |
|---|---|
BIOS (SeaBIOS, qemu-system-i386) |
Reaches event loop, emits timer heartbeat, no CPU exception log |
UEFI (OVMF, qemu-system-x86_64) |
Reaches event loop, emits timer heartbeat, no CPU exception log |
Now true: 68K applications launch from the Finder and run under the interpreter — see Running 68K applications. Only small test programs have been run so far; real Apple applications are untested. Broader hardware coverage is thin — one confirmed machine is not a compatibility matrix. If you have a vintage or modern box to try it on, we would love your test results — please open an issue.
Secure Boot must be off. The GRUB image is unsigned, so a machine with Secure Boot enabled will refuse the stick before GRUB ever appears.
Full roadmap: BARE_METAL_IMPROVEMENTS.md
The project is under active experimental development. Most features are exercised in QEMU; bare-metal testing is limited to a small number of machines, and compatibility with real System 7 applications remains unverified.
- Hardware Abstraction Layer (HAL): x86 implementation is the primary validated target
- Boot System: Successfully boots via GRUB2/Multiboot2 on x86
- Serial Logging: Module-based logging with runtime filtering (Error/Warn/Info/Debug/Trace)
- Graphics Foundation: VESA framebuffer (800x600x32, 32-bit colour) with QuickDraw primitives including XOR mode
- Desktop Rendering: System 7 menu bar with rainbow Apple logo, icons, and desktop patterns
- Typography: Chicago bitmap font with per-character advance metrics, extended Mac Roman (0x80-0xFF) for European accented characters
- Localization: user-visible strings come from
STR#resources through the Locale Manager, in 38 languages; build English only, one language, or all of them (LOCALE_ALL=1) and pick one at boot withlang=xx; CJK multi-byte encoding infrastructure - Font Manager: Font scaling and style-width metrics, with bold/underline rendering and incomplete italic support; shadow, outline, and condense/extend rendering are not implemented. FOND/NFNT loading is connected through
GetResource, but validation against real application resource forks remains limited - Input System (x86): PS/2 keyboard and mouse, plus USB keyboards, mice and tablets (xHCI)
- Event Manager: Cooperative multitasking via WaitNextEvent with unified event queue
- Memory Manager: Zone-based allocation with 68K interpreter integration; on x86 the application zone takes the machine's free RAM
- Menu Manager: Complete dropdown menus with mouse tracking and SaveBits/RestoreBits
- File System: HFS with B-tree implementation, folder windows with VFS enumeration
- Window Manager: Dragging, resizing (with grow box), layering, activation
- Time Manager: Accurate TSC calibration, microsecond precision, generation checking
- Resource Manager: Resource-map lookup, handle-based loading, and resource-fork updates
- Gestalt Manager: Multi-architecture system information with architecture detection
- TextEdit Manager: Text editing with clipboard integration; mixed-font scrolling and styled paste remain partial (see compatibility gaps)
- Scrap Manager: Classic Mac OS clipboard with multiple flavor support
- SimpleText Application: MDI text editor with open/save and clipboard operations; single-level Undo only, with no Redo
- List Manager: System 7-compatible list controls with keyboard navigation
- Control Manager: Standard and scrollbar controls with CDEF implementation
- Dialog Manager: Keyboard navigation, focus rings, keyboard shortcuts
- Segment Loader: Portable ISA-agnostic 68K segment loading system with relocation
- M68K Interpreter: Runs 68000 applications from an HFS disk: resource fork, A5 world, jump table and
_LoadSeg, with Toolbox traps for memory, resources, QuickDraw, windows, menus, events, dialogs, controls, TextEdit, files and Standard File bridged to the native managers - Sound Manager: Command processing, MIDI-note tone playback, channel management, and callbacks; full MIDI synthesis is not implemented
- Device Manager: DCE management, driver installation/removal, and I/O operations
- Startup Screen: Complete boot UI with progress tracking, phase management, and splash screen
- Color Manager: Color state management with QuickDraw integration
- Desk Accessories: Calculator, Alarm Clock, Key Caps and Note Pad are driven through
SystemClick/SystemEvent. Key Caps uses the built-in US keyboard translation and displays typed or clicked Mac Roman characters; custom layouts and insertion into other windows are not implemented. Chooser has selection scaffolding but no content drawing or live device/AppleTalk discovery (see Known Issues) Accessories use native callback-table registration; loading classicDRVRresources is not implemented. - Control Panels: Desktop Patterns (with colour patterns), Date & Time, Sound, Mouse, Keyboard, Control Strip
- 68K Applications: The test programs in
tests/m68krun fully; traps an application uses that are not bridged yet stop it with the trap's name - Window Definition Procedures (WDEF): Core structure in place, partial dispatch
- Speech Manager: API framework and audio passthrough only; speech synthesis engine not implemented
- Exception Handling (RTE): Return from exception partially implemented (currently halts instead of restoring context)
- Non-x86 platforms: ARM/ARM64 build in CI, and ARM64 mounts its boot volume and reaches the event loop in headless QEMU. Physical hardware startup remains unverified; PowerPC remains experimental (see Platform Porting Status)
- Networking: Experimental x86 E1000 code handles ARP and ICMP echo requests; TCP, UDP, DHCP, and AppleTalk are not implemented, and other platforms have no network driver.
- Printing: No print system
- Apple Events: Inter-application Apple Event messaging is not implemented
- Balloon Help: the Help menu is there; balloons are not
- Advanced Audio: Sample playback, mixing (PC speaker limitation)
- Architecture: x86 supported; ARM/ARM64 build targets and an experimental PowerPC scaffold are selected through the HAL
- Boot Protocol: Multiboot2 (x86), platform-specific bootloaders
- Graphics: VESA framebuffer, 800x600 @ 32-bit color
- Memory Layout: Kernel loads at 1MB physical address (x86)
- Timing: Architecture-agnostic with microsecond precision (RDTSC/timer registers)
Build source and object counts depend on the selected platform and options.
Run make info to see the current counts for your configuration.
- GCC with 32-bit support (
gcc-multilibon 64-bit) - GNU Make
- GRUB tools:
grub-mkrescue(fromgrub2-commonorgrub-pc-bin) - GRUB EFI modules (
grub-efi-amd64-bin) and mtools — required for the UEFI half of the ISO. Without themgrub-mkrescuestill exits 0 but silently emits a BIOS-only image that will not boot any modern machine;make isonow fails loudly if that happens - QEMU for testing (
qemu-system-i386) - Python 3 for resource processing
- xxd for binary conversion
- (Optional) powerpc-linux-gnu cross toolchain for PowerPC builds
sudo apt-get install build-essential gcc-multilib grub-pc-bin grub-efi-amd64-bin mtools xorriso qemu-system-x86 python3 vim-common# Build kernel (x86 by default)
make
# Build for specific platform
make PLATFORM=x86
make PLATFORM=arm # requires ARM cross GCC (defaults to arm-linux-gnueabihf)
make PLATFORM=arm64 # requires an AArch64 cross GCC
make PLATFORM=ppc # experimental; requires PowerPC ELF toolchain
# Create bootable ISO
make iso
# Languages: English is built in; add one locale, or all 37 additional locales (38 total)
make LOCALE_FR=1
make LOCALE_ALL=1
# Build and run in QEMU
make run
# Clean artifacts
make clean
# Display build statistics
make info# Standard run with serial logging
make run
# Manually: 1 GB of RAM (the system uses what it is given) and a USB tablet,
# so the pointer follows the host mouse without capturing it
qemu-system-i386 -cdrom system71.iso -m 1024 -vga std \
-device qemu-xhci,id=xhci -device usb-tablet,bus=xhci.0 \
-serial file:/tmp/serial.log# With console serial output
qemu-system-i386 -cdrom system71.iso -serial stdio -display sdl -m 256M
# Headless (no graphics display)
qemu-system-i386 -cdrom system71.iso -serial stdio -display none -m 256M
# With GDB debugging
make debug
# In another terminal: gdb kernel.elf -ex "target remote :1234"- Getting Started Guide — Step-by-step setup and first run
- Known Issues — Current limitations and workarounds
- Contributing Guide — How to help with development
- Component Guides — Detailed technical documentation:
- Control Manager, Dialog Manager, Font Manager, Event Manager
- Menu Manager, Window Manager, Resource Manager, Serial Logging
- Memory Management — Zone-based allocation system
- Project Architecture — Full documentation index
- Locale Manager — where user-visible strings come from, and
lang=at boot - String Resources — the
STR#tables, one file per language - CJK Support — multi-byte encoding infrastructure
Archaeological Approach with evidence-based implementation:
- Backed by Inside Macintosh documentation and MPW Universal Interfaces
- Important compatibility decisions are grounded in documentation, tests, or recorded investigation
- Goal: behavioral parity with original System 7, not modernization
- Clean-room implementation (no original Apple source code)
tests/m68k/build.sh (needs gcc-m68k-linux-gnu, binutils-m68k-linux-gnu
and hfsutils) builds three test programs — Hello in assembly, Sampler and
Notes in C — and writes them to an HFS disk image:
sh tests/m68k/build.sh
qemu-system-i386 -cdrom system71.iso -hda tests/m68k/out/apps.img -boot d \
-m 1024 -vga std -device qemu-xhci,id=xhci -device usb-tablet,bus=xhci.0The disk mounts on the desktop as "Test Apps"; double-click a program to launch it. Notes is a small editor with a menu bar, a scrolling TextEdit window, alerts, a Find dialog and Open/Save. Any 68000 application on an HFS image can be launched the same way. A trap that is not implemented yet stops the program with an alert naming it, and the serial log has the trap and where it was called from.
- Icon Drag Artifacts: Minor visual artifacts during desktop icon dragging
- 68K Coverage: Only the Toolbox traps the test programs use are bridged; real Apple applications are untested
- No TrueType Support: Bitmap fonts only (Chicago)
- HFS Disk Write-Back: Mounted HFS files can be read, but VFS file edits are kept in a RAM overlay and are not flushed to disk
- No Stability Guarantees: Crashes and unexpected behavior are common
This is primarily a learning/research project:
- Bug Reports: File issues with detailed reproduction steps
- Testing: Report results on different hardware/emulators
- Documentation: Improve existing docs or add new guides
- Inside Macintosh (1992-1994): Official Apple Toolbox documentation
- MPW Universal Interfaces 3.2: Canonical header files and struct definitions
- Guide to Macintosh Family Hardware: Hardware architecture reference
- Mini vMac: System 7 emulator for behavioral reference
- ResEdit: Resource editor for studying System 7 resources
- Ghidra/IDA: For ROM disassembly analysis
This is a clean-room reimplementation for educational and preservation purposes:
- No Apple source code was used
- Based on public documentation and black-box analysis only
- "System 7", "Macintosh", "QuickDraw" are Apple Inc. trademarks
- Not affiliated with, endorsed by, or sponsored by Apple Inc.
Original System 7 ROM and software remain property of Apple Inc.
- Apple Computer, Inc. for creating the original System 7
- Inside Macintosh authors for comprehensive documentation
- Classic Mac preservation community for keeping the platform alive
- 68k.news and Macintosh Garden for resource archives
Planned Work:
- Run real 68K applications and bridge the traps they need
- Add TrueType font support
- CJK bitmap font resources for Japanese, Chinese, and Korean rendering
- Implement additional controls (text fields, pop-ups, sliders)
- Disk write-back for HFS file system
- Advanced Sound Manager features (mixing, sampling)
- Balloon Help, and setting alarms in Alarm Clock
Status: Experimental - Educational - In Development
For questions, issues, or discussion, please use GitHub Issues.