Compile Guide

Instructions for building Metaspero from source for iOS and macOS, configuring CMake presets, attaching JIT, and managing memory entitlements.

Repositories

Prerequisites

brew install cmake ninja glslang python

1. 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 --recursive

MoltenVK 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=NO

Package 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 Payload

Or build directly in Xcode:

cmake --preset ios
open _Build/xcode/Metaspero.xcodeproj

Select 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-swiftui

Build 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-failure

Or open in Xcode:

cmake --preset macos-swiftui
open _Build/xcode-mac/Metaspero.xcodeproj

CMake Presets

ios: iOS device (arm64) Release build
ios-debug: iOS device (arm64) Debug build with tracing
macos-swiftui: macOS native ARM64 SwiftUI application
macos-arm64-fex: macOS native ARM64 CLI and test harness
macos: macOS x86_64 build under Rosetta 2 (upstream compatibility)

4. Running with JIT on iOS

iOS requires an attached debugger for JIT compilation permissions:

  1. Connect LocalDevVPN on your device.
  2. Open StikDebug, select Metaspero, and run the universal.js script.
  3. 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.