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, default config (kiosk mode — Mac menu
31//! // bar suppressed; arrow keys not remapped to numpad).
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 cpu;
54pub mod debug_overlay;
55pub mod disk_image;
56pub mod display;
57mod error;
58pub mod game;
59pub mod loader;
60pub mod machine_profile;
61pub mod managers;
62pub mod memory;
63pub mod menu_model;
64pub mod quickdraw;
65pub mod runner;
66/// Deterministic trap-interaction replays. This is internal test
67/// scaffolding, not part of the runtime API, so it is gated behind the
68/// off-by-default `test-support` feature and is absent from normal builds
69/// and docs.
70#[cfg(feature = "test-support")]
71pub mod scripted_traces;
72pub mod sound;
73pub mod trace;
74pub mod trap;
75mod ui_art;
76pub mod ui_theme;
77
78pub use error::{Error, Result};