Skip to main content

Crate systemless

Crate systemless 

Source
Expand description

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

MacintoshSession is the embedding entry point. Its underlying 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 CpuOps is the narrower register interface used by Toolbox handlers.

§Quick start

use systemless::api::InstructionBudget;
use systemless::systems::macintosh::session::MacintoshSession;

let mut session = MacintoshSession::new(true, None);

// 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 = session.load_bytes(&bytes).unwrap();
session.initialize(&app);

// Bound guest work explicitly; the runner retains its guest clock cadence.
let result = session.advance(InstructionBudget(100_000));
println!("ran {} instructions, running = {}", result.instructions, result.running);

Modules§

api
Small contracts shared with embedding hosts. Guest-specific input and configuration live with their guest implementation.
gpu_compute
Shared wgpu kernels for guest-visible QuickDraw and QD3D results.
systems
Guest environments supported by Systemless.

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.