Crate systemless 

High-Level Emulation (HLE) for classic Macintosh applications.

systemless runs Mac OS Toolbox apps without a real ROM by intercepting 68k A-line trap instructions ($A000–$AFFF) and dispatching them to native Rust handlers. QuickDraw, the Window Manager, the Resource Manager, the Sound Manager, SANE, and the rest of the supported Toolbox surface are reimplemented in Rust. The m68k crate executes guest CPU instructions and models generation-specific architectural state.

Execution model

FixtureRunner owns the CPU, guest memory, and Toolbox dispatcher. Precise single-instruction work uses m68k::CpuCore::step. Budgeted execution uses m68k::CpuCore::run_batch, with FastMem for ordinary guest RAM and Cranelift-compiled hot traces on native targets. WebAssembly uses m68k’s portable trace executor; the guest-visible CPU and HLE contracts are the same in both modes.

The library exposes the full m68k::CpuCore through M68kCpu::core for diagnostics and specialized embedding, while cpu::CpuOps is the narrower register interface used by Toolbox handlers.

Quick start

use systemless::runner::{FixtureRunner, FixtureRunnerConfig};

// Allocate an 8 MiB guest with guest-controlled menu visibility and
// arrow keys left as literal arrow keys.
let config = FixtureRunnerConfig::default();
let mut runner = FixtureRunner::new(8 * 1024 * 1024, config);

// Load a Mac executable (StuffIt archive, MacBinary, or raw
// resource fork — the loader auto-detects the format).
let bytes = std::fs::read("MyGame.sit").unwrap();
let _app = systemless::game::load_game(&mut runner, &bytes).unwrap();

// Step the guest until it halts or the budget runs out.
// The bool is `still_running` — false means the CPU halted.
let (steps_taken, still_running) = runner.run_steps(100_000, None);
println!("ran {} steps, still_running = {}", steps_taken, still_running);

Modules

audio

Host audio output backends.

binhex

BinHex 4.0 decoding for classic Mac single-file containers.

callback_manager

Process-owned Time Manager and Vertical Retrace Manager task records.

cpu

CPU backend built on the m68k crate.

debug_overlay

Shared debug overlay data and text formatting.

disk_image

Read-only extraction helpers for classic Mac disk images.

display

Shared framebuffer rendering for all Systemless frontends.

game

Shared game loading helpers.

loader

68k loader data types: CODE 0 header, jump table entries, and the LoadedApp state record returned by FixtureRunner::load_app.

machine_profile

Canonical guest machine profile used by Systemless’s accuracy harness.

managers

Host-side data structures for Toolbox managers.

memory

Memory subsystem for Mac emulation

menu_model

Frontend-neutral snapshots of the guest Menu Manager state.

quickdraw

QuickDraw rendering primitives.

runner

Fixture Runner - Loading and execution infrastructure

sound

Sound Manager state and mixing engine.

trace

Runtime trace hook for cross-runtime parity comparison.

trap

Trap Dispatcher - modular Mac OS trap handling.

ui_theme

UI theme contract for dialog, menu, control, and text rendering.

Macros

g

g!(advance, (origin_x, origin_y), "row" "row" …) — one glyph.

Structs

EventManagerSnapshot

Architecture-neutral Event Manager state exposed by deterministic fixture runners. This is intentionally semantic: callers can assert queue order, live input, lifecycle delivery, and cursor state on either CPU adapter.

EventProbeResult

Result from one Event Manager queue probe call.

EventQueueProbeSnapshot

Architecture-neutral results from the Event Manager queue probe used by the showcase. Each optional value records the most recent call of that kind, preserving the returned event type even after a later call consumes the queue entry.

EventRecordSnapshot

Architecture-neutral semantic copy of the EventRecord most recently exposed to guest code. Keeping the full-width message and posting tick here lets 68K and PowerPC showcase probes assert identical behavior without reading ABI-specific guest memory layouts.

Enums

Error

Top-level error returned by crate::runner::FixtureRunner and the supporting traps. Variants:

Type Aliases

Result

Result<T, Error> shorthand for any systemless operation.