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.

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.

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.