Building Qt 6.11.0 for iOS Simulator on Apple Silicon (M1/M2/M3): A Complete Guide

How to Build Qt 6.11.0 for iOS Simulator on Apple Silicon (ARM64)

Building Qt from source for the iOS Simulator on M1/M2/M3 Macs can be tricky due to specific ARM-related bugs and dependency conflicts. This guide will walk you through the process step-by-step.

Prerequisites:

• Xcode installed with iOS Simulator SDK.
• Qt Creator and Qt 6.11.0 (standard desktop version) installed via Online Installer.
• Python installed (for build scripts).

Step 1: Download Qt Source

The online installer often lacks the necessary source structure for complex cross-compilation. Download the standalone source archive:

Source: Qt Everywhere 6.11.0 Source (qt-everywhere-src-6.11.0.tar.xz)

Step 2: Patch ARM64 Compilation Error

Qt 6.11.0 has a known issue where __yield() is implicitly declared on ARM64, causing the build to fail. We need to include the correct header.

1. Open: ~/Qt/6.11.0/qt-everywhere-src-6.11.0/qtbase/src/corelib/thread/qyieldcpu.h
2. Add the following snippet after the existing includes:

#if defined(Q_PROCESSOR_ARM)
#  include <arm_acle.h>
#endif

Step 3: Build macOS Host Libraries

To cross-compile for iOS, you first need a working host build of Qt on your Mac to provide tools like moc and rcc.

# Add CMake to PATH (adjust path to your Qt Creator installation)
export PATH="~/Qt/Tools/CMake/CMake.app/Contents/bin:$PATH"

# Prepare build directory
mkdir -p ~/Qt/6.11.0/macos-host-arm64 && cd ~/Qt/6.11.0/macos-host-arm64

# Configure
~/Qt/6.11.0/qt-everywhere-src-6.11.0/configure \
  -platform macx-clang \
  -prefix ~/Qt/6.11.0/macos-host-arm64 \
  -opensource -confirm-license \
  -nomake examples \
  -nomake tests \
  -skip qtwebengine \
  -skip qtwebview \
  -release \
  -- -DCMAKE_OSX_ARCHITECTURES=arm64

# Build and Install
cmake --build . --parallel
cmake --install .

Step 4: Build iOS Simulator Libraries

⚠️ Critical Fix:

Even with -skip flags, the configuration might fail due to Python html5lib dependency check in the WebEngine module. The most reliable way is to physically move the module folder.

# Temporarily move WebEngine to avoid dependency check errors
mv ~/Qt/6.11.0/qt-everywhere-src-6.11.0/qtwebengine ~/Qt/6.11.0/qtwebengine_backup

# Prepare iOS Simulator build directory
mkdir -p ~/Qt/6.11.0/ios-sim-arm64 && cd ~/Qt/6.11.0/ios-sim-arm64

# Configure for iOS Simulator
~/Qt/6.11.0/qt-everywhere-src-6.11.0/configure \
    -platform macx-ios-clang \
    -release \
    -sdk iphonesimulator \
    -prefix ~/Qt/6.11.0/ios-sim-arm64 \
    -qt-host-path ~/Qt/6.11.0/macos-host-arm64 \
    -opensource -confirm-license \
    -nomake examples \
    -nomake tests \
    -skip qtwebengine \
    -skip qtpdf \
    -skip qtwebview \
    -device-option IOS_SIMULATOR_ARCH=arm64 \
    -- -DCMAKE_OSX_ARCHITECTURES=arm64

# Build and Install
cmake --build . --parallel
cmake --install .

Step 5: Setup Qt Creator

Register your custom build in Qt Creator:

• Go to Settings > Qt Versions > Add.
• Select ~/Qt/6.11.0/ios-sim-arm64/bin/qmake.

Step 6: Create the iOS Kit

Configure your New Kit as shown in the screenshot below. Ensure the Qt Version points to your newly built libraries and the CMake generator is set to Xcode.

Reference: Manual Kit Configuration in Qt Creator Preferences

Success! Your setup is complete. You can now develop and debug iOS applications directly on your Mac M1/M2/M3 using a native ARM64 Qt build for the simulator.