This repository is a Dolphin emulator fork with an iOS/tvOS app (iCube). Most agent work happens in Source/iOS/App/ (Swift/ObjC UI) or Source/Core/ (C++ emulator).
Start with GitHub ownership and handoffs for current issue/PR ownership and release priorities. GitHub issues, pull requests and milestones are the project-management source of truth for Claude, Codex and local sessions. Check the owner and linked PRs before editing, record the session/branch/checkpoint, and preserve tested versus pending work before handing off or archiving. Do not start a second implementation for already-owned work.
Read docs/HANDOFF.md for implementation history, design-system context and traps; reconcile its dated snapshots against the live GitHub records. Continue release work through the existing App Store tracker #51 and linked milestone/issues.
| Area | Path |
|---|---|
| iOS/tvOS app (Tuist) | Source/iOS/App/ |
| App UI (Swift) | Source/iOS/App/Common/Swift/ |
| Emulation bridge | Source/iOS/App/Common/Emulation/ |
| Dolphin core (C++) | Source/Core/ |
| iOS core xcframework build | BuildiOSXCFramework.py → build/xcframework/ |
| iOS build docs | Source/iOS/BUILDING.md |
git submodule update --init --recursive
brew install cmake ninja tuist bartycrouch
cd Source/iOS/App && tuist generateOpen Source/iOS/App/iCube.xcworkspace. Do not rely on the root Readme.md iOS section alone — use Source/iOS/BUILDING.md.
For iOS Simulator builds, rebuild the xcframework with simulator slices first:
python3 BuildiOSXCFramework.py -aPrefer targeted checks over full core rebuilds:
- Swift/ObjC UI only — build the app scheme without touching C++:
xcodebuild -workspace Source/iOS/App/iCube.xcworkspace \ -scheme "iCube (NJB)" -configuration "Debug (Non-Jailbroken)" \ -destination "generic/platform=iOS" CODE_SIGNING_ALLOWED=NO build
- C++ core change — expect a long rebuild via
BuildiOSXCFramework.pyor the Xcode Build Dolphin Core phase. - Unit tests —
iCubeTeststarget via schemeiCube (NJB)test action.
- iOS and tvOS share most Swift sources; gate platform-specific APIs with
#if os(iOS)/#if os(tvOS). - Tuist project definition:
Source/iOS/App/Project.swift. Regenerate withtuist generateafter structural changes. - ObjC notification name constants use
FOUNDATION_EXPORTin headers and a single definition in one.m/.mmfile — do not define string constants inline in headers. - Swift bridging header:
Source/iOS/App/Common/Swift/BridgingHeader.h.
- Do not commit
Source/iOS/App/iCube.xcodeprojoriCube.xcworkspace(gitignored; Tuist-generated). - Do not assume simulator builds work out of the box — the committed xcframework may be device-only.
- Do not run a full Dolphin desktop build to validate an iOS UI tweak.
GitHub Actions workflow: .github/workflows/build.yml — builds the PVlibDolphin xcframework, runs tuist generate, then archives the iCube (NJB) / iCube (JB) schemes from iCube.xcworkspace. release.yml does the same for a published release. There is no committed Xcode project.