linux-apple-cross.md

Guide for cross compiling iOS Mods on Linux (or Windows)

Gist inspired from https://gist.github.com/matcool/abb65ee59ded3766717c673014c3a2a7

Requirements

• clang
• cmake (duh)
• git
• theos (for the sdk)
• Xcode
• 20 GB of storage minimum

Install the following dependencies:

clang cmake git patch python libssl-dev lzma-dev libxml2-dev xz bzip2 cpio libbz2 zlib1g-dev bash curl sudo make libssl-devel lzma-devel libxml2-devel

Install Xcode here: https://developer.apple.com/download/all/?q=xcode (requires an Apple Account) It should end in .xip, ensure you get the latest version available.

1. Setting up theos

Install theos, it's recommended to use their install script, but you can install it manually if you wish.

You do not need swift, but you will need the SDK for iPhoneOS. For this guide, I will be using the 16.5 SDK.

2. Cloning OSXCross & Extracting Xcode XIP

Clone the OSXCross repo, which will be the toolchain essentially. For this guide, I will be using this commit of OSXCross: https://github.com/tpoechtrager/osxcross/tree/121ce150c7857a9474dfff8a8e431482806b3e1b, and Xcode version 15.1 Move the Xcode_15.1.xip (or whichever version) to the repo's directory.

You may have to use a different command depending on the guide in the README of OSXCross

# Cloning to home dir is optional, but be sure you know where it is.
git clone https://github.com/tpoechtrager/osxcross ~/osxcross
cd ~/osxcross
./tools/gen_sdk_package_pbzx.sh Xcode_15.1.xip

After waiting for the extraction, you should see new files in the base directory. For me, I received two files: MacOSX14.sdk.tar.xz & MacOSX14.2.sdk.tar.xz. It's recommended to use the latest version, which for me will be MacOSX14.2.sdk.tar.xz.

Move the tar to the tarballs directory. We will use that directory later.

3. Patching OSXCross

You will need to patch a certain file for OSXCross, located in wrapper/main.cpp. Create a new file in the parent directory called wrapper.patch, with the following contents:

diff --git a/wrapper/main.cpp b/wrapper/main.cpp
index c29839a..a72d101 100644
--- a/wrapper/main.cpp
+++ b/wrapper/main.cpp
@@ -252,8 +252,7 @@ constexpr struct Opt {
          valseparator(valseparator),
          valseparatorlen(valseparator ? constexprStrLen(valseparator) : 0) {}
 } opts[] = {
-  {"-mmacos-version-min", versionmin, true, false, "="},
-  {"-mmacosx-version-min", versionmin, true, false, "="},
+  {"-miphoneos-version-min", versionmin, true, false, "="},
   {"-stdlib", stdlib, true, false, "="},
   {"-arch", arch, true},
   {"-m16", arch},

Then type git apply wrapper.patch to apply the patches.

Or if you want to edit the file manually, edit wrapper/main.cpp and search for -mmacos-version-min. Replace the first instance with -miphoneos-version-min, and remove the -mmacosx-version-min line.

After that, edit the tools/toolchain.cmake file to replace Darwin with iOS

- set(CMAKE_SYSTEM_NAME "Darwin")
+ set(CMAKE_SYSTEM_NAME "iOS")

4. Building OSXCross

Now that you have patched OSXCross, you are ready to build! Simply type

./build.sh

and wait for the build process to complete.

After the build process completes, ensure that you set your .bashrc or .zshrc to include:

export THEOS=~/theos # Add this if it isn't already there after you installed Theos.
export PATH="/home/fire/osxcross/target/bin:$PATH" # Replace fire with your username.

Then restart your terminal.

5. Symlinking

Assuming that you had already installed Theos with the SDK, you will need to symlink the SDK to OSXCross, since by default, OSXCross assumes you are compiling for MacOS, which is not what this guide is focused on. To resolve this, we will symlink the iPhone SDK to the SDK directory.

# Replace fire with your username, and iPhoneOS16.5.sdk with the version you installed for iPhoneOS.
ln -s $THEOS/sdks/iPhoneOS16.5.sdk /home/fire/osxcross/target/SDK/iPhoneOS16.5.sdk
ln -s $THEOS/sdks/iPhoneOS16.5.sdk /home/fire/osxcross/target/SDK/MacOSX16.5.sdk

6. Building the mod

Now we are basically done. The only thing needed is to set a few variables for CMake, which will be in the script below:

build.sh

# Feel free to adjust this however you'd like.
export OSXCROSS="/home/$USER/osxcross"
export SDK="$OSXCROSS/target/SDK/iPhoneOS16.5.sdk"
export OSXCROSS_SDKROOT="$OSXCROSS/target/SDK/MacOSX16.5.sdk"

# You may need to adjust the darwin compiler versions.
export CC="$OSXCROSS/target/bin/arm64-apple-darwin23.2-clang"
export CXX="$OSXCROSS/target/bin/arm64-apple-darwin23.2-clang++"
export LDFLAGS="-fuse-ld=$OSXCROSS/target/bin/arm64-apple-darwin23.2-ld" # otherwise you'll get a `ld: unrecognised emulation mode: llvm` error

arm64-apple-darwin23.2-cmake -B build-ios -DGEODE_TARGET_PLATFORM=iOS \
  -DCMAKE_SYSTEM_NAME=iOS \
  -DCMAKE_BUILD_TYPE=RelWithDebInfo \
  -DCMAKE_OSX_ARCHITECTURES=arm64 \
  -DCMAKE_OSX_SYSROOT="$SDK" \
  -DCMAKE_OSX_DEPLOYMENT_TARGET=14.0 \
  -DCMAKE_C_COMPILER_TARGET=arm64-apple-ios14.0 \
  -DCMAKE_CXX_COMPILER_TARGET=arm64-apple-ios14.0

# compiler target is to get around the `using sysroot for 'iPhoneOS' but targeting 'MacOSX'` message.

cmake --build build --config RelWithDebInfo

Additional Notes

I haven't tested this guide on Windows, or tried compiling a MacOS mod instead. If you ignore some parts of this guide such as the patching, I wouldn't see why it wouldn't be possible to compile a MacOS mod. Also there may be more things to patch, so this guide may be updated to reflect it. I may also even fork the repository to include the changes.

I used Arch Linux to test building the mod, but any other distro should work, assuming you have the up to date versions of the dependencies.