Debugging

Debugging

Source of truth: dev-docs/debugging.md in the repo. Highlights:

Logging

• src/log.rs defines log! (always prints) and log_dbg! (only for modules listed in ENABLED_MODULES in that file).
• Useful module combos:
  • touchHLE::abi + touchHLE::dyld — a trace of nearly all guest→host calls.
  • touchHLE::mem — guest memory allocations/deallocations.

Crashes

• Guest panic output includes registers r0–r13/SP/LR/PC and a frame-pointer stack trace — open the binary in Ghidra/IDA to interpret it.
• Host panics: rerun with RUST_BACKTRACE=1 on a debug build for readable symbols.

Finding unimplemented APIs

# dumps classes/selectors/functions the app requests and how they're handled
touchHLE --dump=linking-info --dump-file=DUMP.txt app.app

# convenience wrapper (requires jq)
dev-scripts/log-unimplemented.sh app.app

This is the main tool to decide what to implement next: look for unimplemented entries in the dump.

Smoke-testing an app in CI

Workflow run_ipa.yml (Actions → Download and run IPA): give it a direct .ipa/.app.zip URL, optionally run_seconds (default 60) and extra_args (e.g. --scale-hack=2). It builds and runs the app on Linux (xvfb), Windows and macOS — good for regression checks without a local device.

GDB

gdb.rs provides a GDB stub — attach with a desktop gdb to inspect the guest.