Ctrlk
For the complete documentation index, see llms.txt. This page is also available as Markdown.

Virtualizing macOS

Run macOS in a virtual machine to build Provenance from source without a Mac

If you don't have a Mac but want to build Provenance from source, you can run macOS in a virtual machine. This guide covers setting up a macOS VM on Windows or Linux.

Most users don't need this. Install Provenance from the App Store or sideload a pre-built .ipa instead. A macOS VM is only needed for building from source.

Virtualization Options

Best for: Windows users with Intel processors

Requirements

  • CPU: Intel processor with VT-x/VT-d support (AMD works but requires extra patches)

  • RAM: 8 GB minimum (16 GB recommended)

  • Storage: 80+ GB free disk space

  • Software: VMware Workstation Player (free for personal use) or Workstation Pro

Setup

  1. Install VMware Workstation and the VMware Unlocker (enables macOS as a guest OS option)

  2. Create a new VM:

    • Select Apple Mac OS X as the guest OS

    • Allocate at least 4 GB RAM (8 GB recommended for Xcode)

    • Set disk size to at least 80 GB (Xcode alone is ~35 GB)

  3. Configure hardware:

    • Processors: 2+ cores

    • USB Controller: Set to USB 2.0 (required for iOS device detection — USB 3.0 passthrough is unreliable in VMs)

    • Enable:

      • Automatically connect new USB devices

      • Show all USB input devices

      • Share Bluetooth devices with the virtual machine

  4. Install macOS from your installation media

  5. Install VMware Tools after macOS boots (improves graphics, clipboard sharing, and performance)

Post-Install

  1. Update macOS — Open System Settings → General → Software Update

  2. Install Xcode — Download from the App Store (free, ~35 GB)

  3. Open Terminal — Applications → Utilities → Terminal

Continue to Building from Source.

Best for: Free, cross-platform option

Requirements

  • CPU: Intel or AMD with virtualization support

  • RAM: 8 GB minimum

  • Storage: 80+ GB free

  • Software: VirtualBox (free and open source)

Setup

  1. Install VirtualBox and the Extension Pack

  2. Create a new VM:

    • Type: Mac OS X, Version: macOS 64-bit

    • RAM: 4096 MB minimum (8192 MB recommended)

    • Create a virtual hard disk: 80 GB or more (VDI, dynamically allocated)

  3. Configure VM settings:

    • System → Processor: 2+ CPUs

    • Display → Video Memory: 128 MB

    • USB: Enable USB 2.0 (EHCI) Controller

  4. Apply required patches — VirtualBox needs command-line tweaks to run macOS:

  5. Install macOS and then install Xcode

VirtualBox macOS performance is generally worse than VMware. Expect longer build times.

Best for: Running a second macOS version on an existing Mac (Apple Silicon or Intel)

If you have a Mac but need a different macOS version for Xcode compatibility:

  1. Download UTM (free from GitHub, or paid on App Store)

  2. Download a macOS IPSW from Apple or use the built-in installer

  3. Create a new VM → Virtualize → macOS

  4. Allocate RAM and storage, then install

On Apple Silicon Macs, UTM uses Apple's native Virtualization.framework for near-native performance.

Performance Tips

Virtual machines are slower than native hardware. These tips help:

  • Allocate adequate RAM — 8 GB for the VM if your host has 16+ GB

  • Use an SSD — VM disk I/O on a spinning hard drive is painfully slow

  • Close unnecessary host apps — Free up CPU and RAM for the VM

  • Use Release builds — When building Provenance in Xcode, always use the Release scheme (Debug builds are 5-10x slower and even more so in a VM)

  • Disable Spotlight indexing inside the VM — System Settings → Siri & Spotlight → uncheck categories

Troubleshooting

iOS device not detected over USB

  • Make sure VMware/VirtualBox is in focus (click inside the macOS window) before plugging in your device — otherwise the host OS grabs the USB connection

  • Set USB Controller to USB 2.0 (not 3.0) in VM settings

  • On the device, tap Trust when the "Trust This Computer?" dialog appears

  • In VMware: VM menu → Removable Devices → verify your device is connected to the VM

Cannot detect Apple TV 4K over WiFi

Apple TV 4K uses WiFi for Xcode pairing (no USB port). VMs default to NAT networking, which blocks local network discovery.

Fix: Change the VM's network adapter from NAT to Bridged (or Custom → VMnet0) so the VM connects directly to your local network. This enables Bonjour/mDNS discovery needed for Apple TV pairing.

macOS won't boot or shows a black screen

  • Verify your CPU supports hardware virtualization (Intel VT-x / AMD-V) — enable it in BIOS settings

  • For VMware: Ensure the Unlocker is properly installed

  • For VirtualBox: Verify all command-line patches were applied correctly

  • Try a different macOS version — some versions work better with certain VM software

Display resolution is wrong or too small

  • VMware: Install VMware Tools, then use View → Autosize → Autofit Guest

  • VirtualBox: Install Guest Additions (limited macOS support), or set resolution manually:

  • In macOS: System Settings → Displays → choose "Default for Display" or select a specific resolution

Xcode build is extremely slow

  • Allocate more CPU cores and RAM to the VM

  • Use an SSD for VM storage

  • Build the Release scheme (not Debug)

  • Close Xcode's Simulator — it's not needed when deploying to a physical device

  • Consider using a pre-built .ipa via sideloading instead

Alternative: Hackintosh

Instead of a VM, you can install macOS directly on compatible PC hardware (a "Hackintosh"). This gives near-native performance but requires compatible hardware and more setup effort.

Resources:

Hackintosh setups are not officially supported by Apple and require specific hardware. Research compatibility before attempting.

Reminder: Most users should install from the App Store or sideload instead of building from source. A macOS VM is only needed for compiling Provenance yourself.

PreviousProvenance Plus
NextLaunch ROMs via URL

Last updated