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//! [`MacintoshSession`](systems::macintosh::session::MacintoshSession) is the
13//! embedding entry point. Its underlying
14//! [`FixtureRunner`](systems::macintosh::runner::FixtureRunner) owns the CPU,
15//! guest memory, and Toolbox dispatcher. Precise single-instruction work uses
16//! [`m68k::CpuCore::step`]. Budgeted execution uses
17//! [`m68k::CpuCore::run_batch`], with FastMem for ordinary guest RAM and
18//! Cranelift-compiled hot traces on native targets. WebAssembly uses m68k's
19//! portable trace executor; the guest-visible CPU and HLE contracts are the
20//! same in both modes.
21//!
22//! The library exposes the full [`m68k::CpuCore`] through
23//! [`M68kCpu::core`](systems::macintosh::cpu::M68kCpu::core) for diagnostics and specialized
24//! embedding, while [`CpuOps`](systems::macintosh::cpu::CpuOps) is the narrower register interface used by
25//! Toolbox handlers.
26//!
27//! # Quick start
28//!
29//! ```no_run
30//! use systemless::api::InstructionBudget;
31//! use systemless::systems::macintosh::session::MacintoshSession;
32//!
33//! let mut session = MacintoshSession::new(true, None);
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 = session.load_bytes(&bytes).unwrap();
39//! session.initialize(&app);
40//!
41//! // Bound guest work explicitly; the runner retains its guest clock cadence.
42//! let result = session.advance(InstructionBudget(100_000));
43//! println!("ran {} instructions, running = {}", result.instructions, result.running);
44//! ```
45//!
46//! [`m68k`]: https://crates.io/crates/m68k
47
48#![deny(rustdoc::broken_intra_doc_links)]
49
50pub mod api;
51mod error;
52mod fast_hash;
53pub mod systems;
54
55// Compatibility module paths for existing embedders.
56pub(crate) use systems::macintosh::adb;
57#[deprecated(note = "use `systemless::systems::macintosh::audio`")]
58pub mod audio {
59    pub use crate::systems::macintosh::audio::*;
60}
61#[deprecated(note = "use `systemless::systems::macintosh::binhex`")]
62pub mod binhex {
63    pub use crate::systems::macintosh::binhex::*;
64}
65#[deprecated(note = "use `systemless::systems::macintosh::callback_manager`")]
66pub mod callback_manager {
67    pub use crate::systems::macintosh::callback_manager::*;
68}
69pub(crate) use systems::macintosh::cfm;
70pub(crate) use systems::macintosh::collection_manager;
71pub(crate) use systems::macintosh::control_manager;
72pub(crate) use systems::macintosh::copy_bits;
73#[deprecated(note = "use `systemless::systems::macintosh::cpu`")]
74pub mod cpu {
75    pub use crate::systems::macintosh::cpu::*;
76}
77#[cfg(feature = "debug")]
78#[deprecated(note = "use `systemless::systems::macintosh::debug`")]
79pub mod debug {
80    pub use crate::systems::macintosh::debug::*;
81}
82#[deprecated(note = "use `systemless::systems::macintosh::debug_overlay`")]
83pub mod debug_overlay {
84    pub use crate::systems::macintosh::debug_overlay::*;
85}
86#[deprecated(note = "use `systemless::systems::macintosh::disk_image`")]
87pub mod disk_image {
88    pub use crate::systems::macintosh::disk_image::*;
89}
90#[deprecated(note = "use `systemless::systems::macintosh::display`")]
91pub mod display {
92    pub use crate::systems::macintosh::display::*;
93}
94pub(crate) use systems::macintosh::event_queue;
95pub(crate) use systems::macintosh::execution_kernel;
96pub(crate) use systems::macintosh::execution_m68k;
97pub(crate) use systems::macintosh::execution_native;
98#[deprecated(note = "use `systemless::systems::macintosh::game`")]
99pub mod game {
100    pub use crate::systems::macintosh::game::*;
101}
102pub(crate) use systems::macintosh::guest_call;
103pub(crate) use systems::macintosh::guest_procedure;
104pub(crate) use systems::macintosh::list_manager;
105#[deprecated(note = "use `systemless::systems::macintosh::loader`")]
106pub mod loader {
107    pub use crate::systems::macintosh::loader::*;
108}
109pub(crate) use systems::macintosh::mac_roman;
110#[deprecated(note = "use `systemless::systems::macintosh::machine_profile`")]
111pub mod machine_profile {
112    pub use crate::systems::macintosh::machine_profile::*;
113}
114#[deprecated(note = "use `systemless::systems::macintosh::managers`")]
115pub mod managers {
116    pub use crate::systems::macintosh::managers::*;
117}
118#[deprecated(note = "use `systemless::systems::macintosh::memory`")]
119pub mod memory {
120    pub use crate::systems::macintosh::memory::*;
121}
122pub(crate) use systems::macintosh::menu_manager;
123#[deprecated(note = "use `systemless::systems::macintosh::menu_model`")]
124pub mod menu_model {
125    pub use crate::systems::macintosh::menu_model::*;
126}
127pub(crate) use systems::macintosh::mixed_mode;
128pub(crate) use systems::macintosh::process_context;
129pub(crate) use systems::macintosh::process_manager;
130#[deprecated(note = "use `systemless::systems::macintosh::quickdraw`")]
131pub mod quickdraw {
132    pub use crate::systems::macintosh::quickdraw::*;
133}
134#[deprecated(note = "use `systemless::systems::macintosh::runner`")]
135pub mod runner {
136    pub use crate::systems::macintosh::runner::*;
137}
138#[cfg(feature = "test-support")]
139#[deprecated(note = "use `systemless::systems::macintosh::scripted_traces`")]
140pub mod scripted_traces {
141    pub use crate::systems::macintosh::scripted_traces::*;
142}
143#[deprecated(note = "use `systemless::systems::macintosh::sound`")]
144pub mod sound {
145    pub use crate::systems::macintosh::sound::*;
146}
147pub(crate) use systems::macintosh::text_edit;
148pub(crate) use systems::macintosh::thread_manager;
149#[deprecated(note = "use `systemless::systems::macintosh::trace`")]
150pub mod trace {
151    pub use crate::systems::macintosh::trace::*;
152}
153#[deprecated(note = "use `systemless::systems::macintosh::trap`")]
154pub mod trap {
155    pub use crate::systems::macintosh::trap::*;
156}
157pub(crate) use systems::macintosh::ui_art;
158#[deprecated(note = "use `systemless::systems::macintosh::ui_theme`")]
159pub mod ui_theme {
160    pub use crate::systems::macintosh::ui_theme::*;
161}
162pub(crate) use systems::macintosh::window_manager;
163
164pub use error::{Error, Result};
165pub use event_queue::{
166    EventManagerSnapshot, EventProbeResult, EventQueueProbeSnapshot, EventRecordSnapshot,
167};