Building for iOS

iPlug2 supports building Audio Unit v3 (AUv3) plugins for iOS and iPadOS, embedded in a standalone app.

Prerequisites

Install Xcode 13+

Download from the Mac App StoreFor visionOS: Xcode 15+ with visionOS SDK

Install iOS SDK

iOS SDK is included with Xcode. Verify installation:

xcodebuild -showsdks | grep ios

Set up Apple Developer account

Required for device testing and distribution:

Enroll at developer.apple.com
Add your Apple ID in Xcode > Settings > Accounts

Project Structure

MyPlugin/
├── config/
│   └── MyPlugin-ios.xcconfig       # iOS build configuration
└── projects/
    ├── MyPlugin-iOS.xcodeproj/     # Xcode project
    │   └── xcshareddata/
    │       └── xcschemes/
    │           ├── iOS-APP.xcscheme        # Standalone app
    │           └── iOS-AUv3.xcscheme       # AUv3 plugin
    └── MyPlugin-iOS.entitlements   # App capabilities

AUv3 Architecture

On iOS, AUv3 plugins are embedded inside a standalone app:

MyPlugin.app/
└── PlugIns/
    └── MyPlugin.appex          # AUv3 app extension

You must run the standalone app at least once to register the AUv3 with iOS. After that, the plugin appears in GarageBand, Cubasis, and other AUv3 hosts.

Building with Xcode

Device vs Simulator

iOS Device

Destination: Any iOS DeviceRequires code signing and provisioning profile

iOS Simulator

Destination: iPhone/iPad SimulatorNo code signing required, faster builds

Building in Xcode

Open project

open projects/MyPlugin-iOS.xcodeproj

Select scheme and destination

Scheme: iOS-APP (builds both app and AUv3)
Destination: Choose device or simulator

Configure signing

Project Settings > Signing & Capabilities

Team: Select your Apple Developer team
Bundle Identifier: Set unique ID (e.g., com.yourcompany.myplugin)
Automatically manage signing: Enable for automatic provisioning

Build and run

Press ⌘R or Product > RunXcode will:

Build the app and AUv3 extension
Install on device/simulator
Launch the app

Building from Command Line

# Build for simulator
xcodebuild -project projects/MyPlugin-iOS.xcodeproj \
  -scheme iOS-APP \
  -configuration Release \
  -sdk iphonesimulator \
  -destination 'platform=iOS Simulator,name=iPhone 15'

Platform Variants

iOS

Standard iPhone and iPad support.

Minimum deployment: iOS 14 (configurable)
SDK: iphoneos (device), iphonesimulator (simulator)
Architecture: arm64 (device), arm64 x86_64 (simulator)

visionOS

Apple Vision Pro support.

Minimum deployment: visionOS 1.0
SDK: xros (device), xrsimulator (simulator)
Requires: Xcode 15+

visionOS builds use the same project as iOS. Xcode automatically adapts the UI for spatial computing.

Build Settings

Deployment Target (from common-ios.xcconfig)

// Minimum iOS version
IPHONEOS_DEPLOYMENT_TARGET = 15  // iOS 15+

// C++ standard
CLANG_CXX_LANGUAGE_STANDARD = c++17
CLANG_CXX_LIBRARY = libc++

Architecture Settings

// iOS Device (arm64 only)
ARCHS[sdk=iphoneos*] = arm64

// iOS Simulator (Universal for Intel and Apple Silicon Macs)
ARCHS[sdk=iphonesimulator*] = arm64 x86_64

// visionOS
ARCHS[sdk=xros*] = arm64
ARCHS[sdk=xrsimulator*] = arm64

Preprocessor Defines

NOMINMAX                 // Disable min/max macros
AUv3_API                 // Audio Unit v3
IPLUG_EDITOR=1           // Has UI
IPLUG_DSP=1              // Has DSP

Code Signing

Automatic Signing (Recommended)

Enable automatic signing

Project Settings > Signing & Capabilities

Enable Automatically manage signing
Select your Team

Set bundle identifier

Use reverse domain notation:

com.yourcompany.myplugin

Xcode handles provisioning

Xcode automatically:

Creates provisioning profiles
Manages certificates
Signs app and extension

Manual Signing

For advanced control:

Create App ID

Go to developer.apple.com
Identifiers > App IDs > +
Register com.yourcompany.myplugin

Create provisioning profile

Profiles > +
Choose iOS App Development or App Store
Select your App ID and certificates
Download and install profile

Configure Xcode

Project Settings > Signing & Capabilities

Disable Automatically manage signing
Select your Provisioning Profile

App Capabilities (Entitlements)

Edit MyPlugin-iOS.entitlements:

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
    <!-- Required for AUv3 -->
    <key>com.apple.security.application-groups</key>
    <array>
        <string>group.com.yourcompany.myplugin</string>
    </array>
    
    <!-- Inter-App Audio (optional) -->
    <key>inter-app-audio</key>
    <true/>
    
    <!-- Background Audio -->
    <key>audio</key>
    <true/>
</dict>
</plist>

App Groups allow the app and AUv3 extension to share data (presets, user settings, etc.).

Testing AUv3 Plugins

Testing in GarageBand

Run standalone app

Build and run your app on device/simulatorThis registers the AUv3 with iOS

Open GarageBand

Create a new song

Add plugin

Create an instrument/audio track
Tap the track controls
Plug-ins & EQ > Audio Unit Extensions
Find your plugin in the list

Test functionality

Verify UI appears correctly
Test parameter changes
Check audio processing
Test preset saving/loading

Testing in AUv3 Host App

Use a dedicated test host like:

AUM (Audio Mixer) - App Store
ApeMatrix - App Store
AudioBus - App Store

Debugging

Debugging the Standalone App

Set breakpoints

Add breakpoints in your plugin code

Run with debugger

Press ⌘R in XcodeDebugger attaches to the app process

Trigger breakpoints

Interact with your plugin UI or process audio

Debugging the AUv3 Extension

AUv3 runs in a separate process from the host app.

Launch host app

Start GarageBand or another AUv3 hostDo not launch from Xcode

Attach debugger to extension

In Xcode:

Debug > Attach to Process by PID or Name
Enter: MyPlugin (your extension name)
Click Attach

Load plugin in host

Load your plugin in the host appXcode debugger will now catch breakpoints

Set breakpoints before attaching to ensure they’re registered.

Console Logging

Use NSLog for debugging output visible in Xcode console:

#import <Foundation/Foundation.h>

void MyPlugin::ProcessBlock(iplug::sample** inputs, iplug::sample** outputs, int nFrames)
{
  NSLog(@"ProcessBlock called with %d frames", nFrames);
  // ...
}

Build Output

Built apps are placed in Xcode’s derived data folder:

~/Library/Developer/Xcode/DerivedData/MyPlugin-iOS-xxxxx/Build/Products/Release-iphoneos/
└── MyPlugin.app/
    ├── MyPlugin                    # App executable
    └── PlugIns/
        └── MyPlugin.appex/         # AUv3 app extension
            └── MyPlugin            # Extension executable

Distribution

TestFlight (Beta Testing)

Archive the app

Product > ArchiveXcode creates a distribution archive

Upload to App Store Connect

Window > Organizer
Select your archive
Distribute App > App Store Connect
Follow the wizard to upload

Configure in App Store Connect

Go to appstoreconnect.apple.com
My Apps > Your App > TestFlight
Add internal/external testers
Distribute build

App Store Release

Prepare app metadata

In App Store Connect:

App name and description
Screenshots (required for each device size)
App icon (1024x1024)
Privacy policy URL

Submit for review

Select your uploaded build
Complete all required fields
Submit for Review

Wait for approval

Apple reviews apps within 24-48 hoursYou’ll be notified of approval or rejection

Troubleshooting

AUv3 not appearing in GarageBand

Cause: Extension not registered or signing issueSolution:

Run standalone app at least once
Ensure both app and extension are code-signed
Check app is installed on same device you’re testing
Restart GarageBand
Check Console.app for errors

Code signing error: No profiles found

Cause: Provisioning profile missing or expiredSolution:

Enable Automatically manage signing
Or create/download provisioning profile manually
Ensure Bundle ID matches App ID
Check team membership is active

App crashes on launch

Cause: Missing frameworks or entitlementsSolution:

Check Console.app for crash logs
Verify all frameworks are embedded
Ensure entitlements are correct (App Groups, etc.)
Test in simulator first for easier debugging

Audio glitches or dropouts

Cause: ProcessBlock too heavy for real-time audioSolution:

Profile with Instruments (Time Profiler)
Reduce DSP complexity
Avoid allocations in ProcessBlock
Check buffer size in host settings
Test on actual device (not simulator)

UI not appearing in AUv3 host

Cause: IGraphics initialization or size issueSolution:

Verify UI initializes correctly in standalone app
Check constraints are set properly
Ensure IGraphics is created in plugin constructor
Test with different AUv3 hosts (AUM, GarageBand, etc.)

CMake Build (Alternative)

iOS projects can also be built with CMake:

# iOS Device
cmake -G Xcode \
  -DCMAKE_SYSTEM_NAME=iOS \
  -DIPLUG2_IOS_PLATFORM=OS \
  ..

# iOS Simulator
cmake -G Xcode \
  -DCMAKE_SYSTEM_NAME=iOS \
  -DIPLUG2_IOS_PLATFORM=SIMULATOR \
  ..

# visionOS Device
cmake -G Xcode \
  -DCMAKE_SYSTEM_NAME=iOS \
  -DIPLUG2_IOS_PLATFORM=VISIONOS \
  ..

See CMake Guide for details.

Next Steps

macOS Build

Build desktop plugins for macOS

Code Signing

Advanced signing and provisioning

App Store

Publishing to the App Store

IGraphics

Building custom UIs

​Prerequisites

​Project Structure

​AUv3 Architecture

​Building with Xcode

​Device vs Simulator

iOS Device

iOS Simulator

​Building in Xcode

​Building from Command Line

​Platform Variants

​iOS

​visionOS

​Build Settings

​Deployment Target (from common-ios.xcconfig)

​Architecture Settings

​Preprocessor Defines

​Code Signing

​Automatic Signing (Recommended)

​Manual Signing

​App Capabilities (Entitlements)

​Testing AUv3 Plugins

​Testing in GarageBand

​Testing in AUv3 Host App

​Debugging

​Debugging the Standalone App

​Debugging the AUv3 Extension

​Console Logging

​Build Output

​Distribution

​TestFlight (Beta Testing)

​App Store Release

​Troubleshooting

​CMake Build (Alternative)

​Next Steps

macOS Build

Code Signing

App Store

IGraphics

Prerequisites

Project Structure

AUv3 Architecture

Building with Xcode

Device vs Simulator

Building in Xcode

Building from Command Line

Platform Variants

iOS

visionOS

Build Settings

Deployment Target (from common-ios.xcconfig)

Architecture Settings

Preprocessor Defines

Code Signing

Automatic Signing (Recommended)

Manual Signing

App Capabilities (Entitlements)

Testing AUv3 Plugins

Testing in GarageBand

Testing in AUv3 Host App

Debugging

Debugging the Standalone App

Debugging the AUv3 Extension

Console Logging

Build Output

Distribution

TestFlight (Beta Testing)

App Store Release

Troubleshooting

CMake Build (Alternative)

Next Steps