Compile Guide
Instructions for building Metaspero from source for iOS and macOS, configuring CMake presets, attaching JIT, and managing memory entitlements.
Repositories
- alamshafil/metaspero - Main iOS & native macOS emulator core (GPL-2.0)
- alamshafil/fexcore-darwin - ARM64 Darwin JIT submodule
- alamshafil/metaspero-website - Documentation and compatibility website
- KytyPS5/KytyPS5 - Upstream PS5 translation layer
Prerequisites
- Apple Silicon Mac running macOS
- Xcode with iOS SDK installed (
xcode-select --install) - CMake, Ninja, glslang, and Python via Homebrew:
brew install cmake ninja glslang python1. Clone Repository & Submodules
Clone recursively to fetch all submodules including the FEXCore Darwin JIT engine:
git clone --recursive https://github.com/alamshafil/metaspero.git
cd metaspero
# If already cloned:
git submodule update --init --recursiveMoltenVK and FFmpeg are downloaded automatically via CMake FetchContent during configuration.
2. Compiling for iOS
Build with the ios preset without code signing so it can be signed during sideloading:
cmake --preset ios
cmake --build --preset ios -- \
CODE_SIGNING_ALLOWED=NO CODE_SIGN_IDENTITY="" CODE_SIGNING_REQUIRED=NOPackage the compiled app bundle into a sideloadable IPA:
mkdir -p _Build/xcode/Payload
cp -R _Build/xcode/frontend/swift/Release-iphoneos/Metaspero.app _Build/xcode/Payload/
cd _Build/xcode
zip -r -q Metaspero.ipa Payload
rm -rf PayloadOr build directly in Xcode:
cmake --preset ios
open _Build/xcode/Metaspero.xcodeprojSelect the Metaspero scheme, choose your connected iOS device, and press Cmd+R.
3. Compiling for macOS (Native ARM64)
This fork runs natively on Apple Silicon using FEXCore dynamic binary translation rather than Rosetta 2.
Build the native macOS SwiftUI app:
cmake --preset macos-swiftui
cmake --build --preset macos-swiftuiBuild the CLI binary and run tests:
cmake --preset macos-arm64-fex
cmake --build --preset macos-arm64-fex
ctest --test-dir _Build/macos-arm64 --output-on-failureOr open in Xcode:
cmake --preset macos-swiftui
open _Build/xcode-mac/Metaspero.xcodeprojCMake Presets
4. Running with JIT on iOS
iOS requires an attached debugger for JIT compilation permissions:
- Connect LocalDevVPN on your device.
- Open StikDebug, select Metaspero, and run the
universal.jsscript. - Return to Metaspero and verify JIT status shows Active before launching a game.
5. Memory Entitlement & Jetsam Protection
By default, iOS Jetsam limits standard apps to roughly 2 GB to 3 GB of RAM. The app includes the increased memory limit entitlement in src/ios_jit.entitlements:
<key>com.apple.developer.kernel.increased-memory-limit</key>
<true/>
<key>get-task-allow</key>
<true/>An in-app toast alerts you when device memory pressure approaches the Jetsam kill threshold.
6. Sideloading & Game Files
Install the IPA via AltStore, SideStore, or TrollStore. Place decrypted game directories in application storage using the iOS Files app:
On My iPhone / Metaspero / [TitleID] /Folders must contain eboot.bin (or main.elf), param.json, and assets.