Skip to main content

systemless/
lib.rs

1//! High-Level Emulation (HLE) for classic Macintosh applications.
2//!
3//! `systemless` runs Mac OS Toolbox apps without a real ROM by intercepting
4//! 68k A-line trap instructions (`$A000`–`$AFFF`) and dispatching them
5//! to native Rust handlers. QuickDraw, the Window Manager, the Resource
6//! Manager, the Sound Manager, SANE, and the rest of the supported Toolbox
7//! surface are reimplemented in Rust. The [`m68k`] crate executes guest CPU
8//! instructions and models generation-specific architectural state.
9//!
10//! # Execution model
11//!
12//! [`FixtureRunner`](runner::FixtureRunner) owns the CPU, guest memory, and
13//! Toolbox dispatcher. Precise single-instruction work uses
14//! [`m68k::CpuCore::step`]. Budgeted execution uses
15//! [`m68k::CpuCore::run_batch`], with FastMem for ordinary guest RAM and
16//! Cranelift-compiled hot traces on native targets. WebAssembly uses m68k's
17//! portable trace executor; the guest-visible CPU and HLE contracts are the
18//! same in both modes.
19//!
20//! The library exposes the full [`m68k::CpuCore`] through
21//! [`M68kCpu::core`](cpu::M68kCpu::core) for diagnostics and specialized
22//! embedding, while [`cpu::CpuOps`] is the narrower register interface used by
23//! Toolbox handlers.
24//!
25//! # Quick start
26//!
27//! ```no_run
28//! use systemless::runner::{FixtureRunner, FixtureRunnerConfig};
29//!
30//! // Allocate an 8 MiB guest with guest-controlled menu visibility and
31//! // arrow keys left as literal arrow keys.
32//! let config = FixtureRunnerConfig::default();
33//! let mut runner = FixtureRunner::new(8 * 1024 * 1024, config);
34//!
35//! // Load a Mac executable (StuffIt archive, MacBinary, or raw
36//! // resource fork — the loader auto-detects the format).
37//! let bytes = std::fs::read("MyGame.sit").unwrap();
38//! let _app = systemless::game::load_game(&mut runner, &bytes).unwrap();
39//!
40//! // Step the guest until it halts or the budget runs out.
41//! // The bool is `still_running` — false means the CPU halted.
42//! let (steps_taken, still_running) = runner.run_steps(100_000, None);
43//! println!("ran {} steps, still_running = {}", steps_taken, still_running);
44//! ```
45//!
46//! [`m68k`]: https://crates.io/crates/m68k
47
48#![deny(rustdoc::broken_intra_doc_links)]
49
50mod adb;
51pub mod audio;
52pub mod binhex;
53pub mod callback_manager;
54mod control_manager;
55pub mod cpu;
56#[cfg(feature = "debug")]
57pub mod debug;
58pub mod debug_overlay;
59pub mod disk_image;
60pub mod display;
61mod error;
62mod event_queue;
63pub use event_queue::{
64    EventManagerSnapshot, EventProbeResult, EventQueueProbeSnapshot, EventRecordSnapshot,
65};
66mod cfm;
67mod collection_manager;
68mod copy_bits;
69mod execution_kernel;
70mod execution_m68k;
71mod execution_native;
72pub mod game;
73mod guest_call;
74mod guest_procedure;
75mod list_manager;
76pub mod loader;
77mod mac_roman;
78pub mod machine_profile;
79pub mod managers;
80pub mod memory;
81mod menu_manager;
82pub mod menu_model;
83mod mixed_mode;
84mod process_context;
85mod process_manager;
86pub mod quickdraw;
87pub mod runner;
88/// Deterministic trap-interaction replays. This is internal test
89/// scaffolding, not part of the runtime API, so it is gated behind the
90/// off-by-default `test-support` feature and is absent from normal builds
91/// and docs.
92#[cfg(feature = "test-support")]
93pub mod scripted_traces;
94pub mod sound;
95mod text_edit;
96mod thread_manager;
97pub mod trace;
98pub mod trap;
99mod ui_art;
100pub mod ui_theme;
101mod window_manager;
102
103pub use error::{Error, Result};