Skip to content
Antimatter

iOS KVM Build Environment

This document details the highly optimized, custom bare-metal virtualization pipeline built to compile the Antimatter iOS companion app on an Ultramarine Linux host.

The Core Objective

Instead of using heavy, resource-hungry abstractions like Docker OSX, we used OSX-KVM (bare-metal virtualization) to run macOS Ventura directly on hardware. This squeezed out the maximum possible speed for compiling iOS apps while keeping the Ultramarine Linux system stable.

Phase 1: Environment Preparation

  • Hardware Analysis: Identified that the / root partition was critically low on space, so we targeted the /home partition (which had 180GB free) to build an 80GB virtual hard drive.
  • Virtualization Dependencies: Installed QEMU, KVM, and libvirt to allow the Intel processor to natively host macOS without emulation lag.
  • Fetching the OS: Pulled down the macOS Ventura recovery image, opting for Ventura instead of Sonoma because it is lighter and consumes fewer resources.

Phase 2: The “Burst Mode” Strategy

To dramatically speed up the installation without permanently crippling the Linux host, we used a two-tier hardware configuration inside OpenCore-Boot.sh:

  • Burst Mode: Temporarily gave the virtual machine 10 CPU threads and 10GB of RAM to power through the macOS installation and the heavy Xcode decompression phase.
  • Daily Driver Mode: Once the heavy lifting was done, dialed the VM back down to 8 CPU threads and 8GB of RAM to safely multitask and code on the Linux host without memory crashes.

Phase 3: Bypassing Apple’s Blocks & Lightning File Transfers

  • The Apple ID Block: Apple blocked the VM from signing into the App Store because of its virtual serial number. Bypassed this by creating an Apple ID on the web and downloading Xcode directly from the Apple Developer Portal.
  • The Version Trap: Realized Xcode 15.4 doesn’t work on Ventura, so pivoted to downloading Xcode 15.2, which is perfectly compatible.
  • The Python Network Bridge: Instead of waiting hours to transfer the massive 12GB Xcode file into the VM, spun up a temporary Python web server on the Linux host (python3 -m http.server 8000). By accessing http://10.0.2.2:8000 inside macOS, transferred the file directly through RAM in seconds.

Phase 4: Xcode Extraction & Setup

  • Decompression: Thanks to Burst Mode, hardware ripped through the 12GB Xcode .xip extraction in less than 5 minutes.
  • Targeting iOS: Installed Xcode into the Applications folder and specifically downloaded the iOS 17.2 Simulator (~7GB) to boot up a virtual iPhone for testing.
  • Overcoming the Verification Timeout: The virtual machine’s CPU completely maxed out (hitting over 400% usage across threads) while cryptographically verifying the massive iOS image, causing a temporary UI timeout (Error Code 32). Safely cleared the hung background service by rebooting the VM and utilizing the cached download to finish the installation.

Phase 5: The Seamless “Code in Linux, Compile in Mac” Workflow

Instead of forcing code writing in a laggy, unaccelerated macOS interface, a zero-sync bridge was built between the two operating systems:

  • The Project Hub: Designated the native Ultramarine directory (~/antimatter/ios) as the master project folder.
  • Bypassing Linux Security: Configured a Samba (SMB) Server and explicitly disabled Fedora’s strict SELinux protections (samba_enable_home_dirs) to allow the home folder to be shared.
  • Mounting the Drive: Connected macOS directly to the virtual host IP (smb://10.0.2.2) and authenticated with Linux user credentials to mount the directory.

The Final “Zero-Sync” Result

There is only one physical copy of the code, resting safely on the fast Linux NVMe SSD. macOS simply looks at the Linux drive through a virtual window. This ensures instantaneous, bidirectional updates when writing code using Linux text editors, while Apple’s heavy, messy compilation files (DerivedData) stay trapped locally inside the macOS virtual disk. Xcode acts purely as a remote engine to compile the code and launch the iOS simulator.