Building for macOS

iPlug2 supports building macOS audio plugins using Xcode, with support for both Intel and Apple Silicon (Universal binaries).

Prerequisites

Install Xcode

Download from the Mac App StoreMinimum version: Xcode 13+ (Xcode 15+ for visionOS)

Install Command Line Tools

xcode-select --install

Download SDKs (optional)

For VST3, AAX, and other plugin formats:

cd iPlug2/Dependencies
./download-iplug-sdks.sh

Project Structure

Each plugin has an Xcode project containing multiple targets:

MyPlugin/
├── MyPlugin.xcworkspace/           # Workspace (optional)
├── config/
│   └── MyPlugin-mac.xcconfig       # Build configuration
└── projects/
    └── MyPlugin-macOS.xcodeproj/   # Xcode project
        └── xcshareddata/
            └── xcschemes/
                ├── VST2.xcscheme
                ├── VST3.xcscheme
                ├── AU.xcscheme          # AUv2
                ├── AUv3.xcscheme        # AUv3
                ├── CLAP.xcscheme
                ├── AAX.xcscheme
                └── APP.xcscheme

Building with Xcode

Opening the Project

Xcode GUI
Command Line

Double-click MyPlugin-macOS.xcodeproj
Or open workspace: MyPlugin.xcworkspace

open projects/MyPlugin-macOS.xcodeproj

Building in Xcode

Select scheme

Choose target from the scheme menu:

VST3 - VST3 plugin
AU - Audio Unit v2
AUv3 - Audio Unit v3 (modern)
CLAP - CLAP plugin
AAX - AAX plugin (requires SDK)
APP - Standalone application

Select configuration

Product > Scheme > Edit SchemeChoose build configuration:

Debug - Development with debug symbols
Release - Optimized for distribution
Tracer - Performance profiling

Build

Product > Build or press ⌘B

Building from Command Line

# Build specific target
xcodebuild -project projects/MyPlugin-macOS.xcodeproj \
  -scheme VST3 \
  -configuration Release

# Build all targets
xcodebuild -project projects/MyPlugin-macOS.xcodeproj \
  -alltargets \
  -configuration Release

Universal Binaries

iPlug2 supports building Universal binaries that run natively on both Intel and Apple Silicon Macs.

Intel (x86_64)

Runs on Intel-based MacsCompatible with all macOS versions

Apple Silicon (arm64)

Runs natively on M1/M2/M3 MacsSignificantly better performance

Building Universal Binaries

Xcode
xcconfig
Command Line

Product > Scheme > Edit Scheme
Run > Info > Build Configuration > Release
Product > Destination > Any Mac
Build Settings > Architectures
- Set to: arm64 x86_64
- Or: $(ARCHS_STANDARD) (default)
Product > Build

Edit config/MyPlugin-mac.xcconfig:

// Build universal binaries
ARCHS = arm64 x86_64
ONLY_ACTIVE_ARCH = NO

xcodebuild -project projects/MyPlugin-macOS.xcodeproj \
  -scheme VST3 \
  -configuration Release \
  ARCHS="arm64 x86_64" \
  ONLY_ACTIVE_ARCH=NO

Universal binaries are recommended for distribution to support all Macs with a single file.

Verifying Universal Binaries

# Check architectures in a binary
lipo -info build-mac/MyPlugin.vst3/Contents/MacOS/MyPlugin

# Expected output:
# Architectures in the fat file: MyPlugin are: x86_64 arm64

# Extract specific architecture
lipo build-mac/MyPlugin.vst3/Contents/MacOS/MyPlugin \
  -extract arm64 -output MyPlugin-arm64

Build Output

Built plugins are placed in build-mac/:

MyPlugin/build-mac/
├── MyPlugin.app/                   # Standalone app (contains AUv3)
│   └── Contents/
│       ├── MacOS/MyPlugin
│       ├── Frameworks/
│       │   └── MyPluginAU.framework/  # AUv3 framework
│       └── PlugIns/
│           └── MyPlugin.appex/        # AUv3 app extension
├── MyPlugin.vst3/                  # VST3 plugin
├── MyPlugin.clap/                  # CLAP plugin
├── MyPlugin.component/             # AUv2 plugin
├── MyPlugin.aaxplugin/             # AAX plugin
├── MyPluginAU.framework/           # AUv3 framework (standalone)
└── MyPlugin.appex/                 # AUv3 app extension (standalone)

AUv3 is embedded inside the standalone app and also built as a standalone framework/appex for use in other hosts.

Deployment Paths

Plugins are automatically symlinked to standard locations:

Format	Default Path
VST3	`~/Library/Audio/Plug-Ins/VST3/`
VST2	`~/Library/Audio/Plug-Ins/VST/`
CLAP	`~/Library/Audio/Plug-Ins/CLAP/`
AUv2	`~/Library/Audio/Plug-Ins/Components/`
AAX	`/Library/Application Support/Avid/Audio/Plug-Ins/`
APP	`~/Applications/`

MacOS uses symlinks by default for faster development. Symlinks update automatically when you rebuild.

Customizing Deployment

Edit common-mac.xcconfig:

// Custom deployment paths
VST3_PATH = $(HOME)/MyPlugins/VST3
AU_PATH = $(HOME)/MyPlugins/Components

Code Signing

Code signing is required for AUv3 plugins and distribution.

Development Signing (Ad-hoc)

For local development only:

# Sign from innermost to outermost
codesign -s - --deep --force build-mac/MyPlugin.app/Contents/Frameworks/MyPluginAU.framework
codesign -s - --deep --force build-mac/MyPlugin.app/Contents/PlugIns/MyPlugin.appex
codesign -s - --deep --force build-mac/MyPlugin.app

# Verify signature
codesign -vvv --deep --strict build-mac/MyPlugin.app

Ad-hoc signing (-s -) is for local development only. These plugins:

Cannot be distributed to other users
Will not run on other machines
Are blocked by Gatekeeper

Distribution Signing

For public distribution, sign with a Developer ID certificate:

Get Developer ID certificate

Enroll in Apple Developer Program
Certificates, Identifiers & Profiles > Certificates
Create Developer ID Application certificate
Download and install in Keychain

Configure code signing

Edit common-mac.xcconfig:

CERTIFICATE_ID = Developer ID Application: Your Name (TEAM_ID)
DEVELOPMENT_TEAM = TEAM_ID  // Found at end of developer.apple.com URL

Sign with hardened runtime

codesign --force --timestamp --options runtime \
  -s "Developer ID Application: Your Name (TEAM_ID)" \
  -v build-mac/MyPlugin.app --deep --strict

The --options runtime flag enables hardened runtime, required for notarization.

Verify signature

# Check code signature
codesign -dvv build-mac/MyPlugin.app

# Verify signature is valid
codesign -vvv --deep --strict build-mac/MyPlugin.app

# Check Gatekeeper assessment
spctl -vvv --assess --type exec build-mac/MyPlugin.app

Notarization

Notarization is required for macOS 10.15+ to avoid Gatekeeper warnings.

Create app-specific password

Go to appleid.apple.com
Sign In > App-Specific Passwords
Generate a new password
Save it securely

Notarize the app

# Create a ZIP for notarization
ditto -c -k --keepParent build-mac/MyPlugin.app MyPlugin.zip

# Submit for notarization
xcrun notarytool submit MyPlugin.zip \
  --apple-id [email protected] \
  --team-id TEAM_ID \
  --password app-specific-password \
  --wait

Use --wait to wait for notarization to complete (takes 5-15 minutes).

Staple the ticket

After successful notarization:

# Staple notarization ticket to app
xcrun stapler staple build-mac/MyPlugin.app

# Verify stapling
xcrun stapler validate build-mac/MyPlugin.app

Stapling embeds the notarization ticket, allowing the app to run offline.

iPlug2 includes a helper script: Scripts/notarise.sh for automated notarization.

Using notarise.sh

cd Scripts
./notarise.sh \
  "$(pwd)/.." \
  "$(pwd)/../MyPlugin/build-mac/MyPlugin.app" \
  "com.yourcompany.myplugin" \
  "[email protected]" \
  "app-specific-password"

Arguments:

Root directory
Path to app/plugin
Bundle ID
Apple ID email
App-specific password

Debugging

Setting Up Debugger

Edit scheme

Product > Scheme > Edit Scheme > Run > Info

Executable: Choose your DAW (e.g., /Applications/REAPER.app)
Or select Ask on Launch to choose at runtime

Set breakpoints

Click in the gutter to add breakpoints in your code

Run debugger

Press ⌘R or Product > RunXcode will:

Build the plugin
Deploy to plugin folder
Launch your DAW
Attach the debugger

Load plugin in DAW

Create a track and load your pluginBreakpoints will trigger when code is executed

LLDB Debugging

For advanced debugging:

# Launch DAW with LLDB
lldb /Applications/REAPER.app/Contents/MacOS/REAPER

# Set breakpoints
(lldb) breakpoint set --name MyPlugin::ProcessBlock
(lldb) breakpoint set --file MyPlugin.cpp --line 42

# Run
(lldb) run

# When breakpoint hits
(lldb) bt           # Backtrace
(lldb) frame variable  # Local variables
(lldb) continue     # Continue execution

Audio Unit Validation

Validate AUv2 plugins with auval:

# List all registered Audio Units
auval -a

# Validate effect (aufx)
auval -v aufx <subtype> <manufacturer>

# Validate instrument (aumu)
auval -v aumu <subtype> <manufacturer>

# Example: Validate IPlugEffect
auval -v aufx Ipef Acme

<subtype> and <manufacturer> are 4-character codes defined in config.h.

Common auval Errors

ERROR: Failed validation

Cause: Plugin not properly registered or has errorsSolution:

Ensure plugin is code-signed
Run the standalone app once to register AUv3
Clear Audio Unit cache: killall -9 AudioComponentRegistrar
Check Console.app for crash logs

WARNING: View has zero size

Cause: UI not initialized properlySolution:

Usually benign, but verify UI appears correctly in DAW
Check IGraphics initialization in plugin constructor

Build Settings

Common Settings (from common-mac.xcconfig)

// Deployment target
MACOSX_DEPLOYMENT_TARGET = 10.13  // Minimum macOS version

// Architectures
ARCHS = arm64 x86_64  // Universal binary

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

// Code signing
CERTIFICATE_ID = Developer ID Application: Your Name (TEAM_ID)
DEVELOPMENT_TEAM = TEAM_ID

Preprocessor Defines

NOMINMAX                 // Disable min/max macros
SWELL_CLEANUP_ON_UNLOAD  // Clean up SWELL resources

// Format-specific
VST3_API                 // VST3 plugin
AU_API                   // Audio Unit v2
AUv3_API                 // Audio Unit v3
CLAP_API                 // CLAP plugin
AAX_API                  // AAX plugin
APP_API                  // Standalone app

// Audio APIs (APP only)
__MACOSX_CORE__          // CoreAudio

// IPlug defines
IPLUG_EDITOR=1           // Has UI
IPLUG_DSP=1              // Has DSP

Troubleshooting

Plugin not loading in DAW

Cause: Architecture mismatch, code signing, or registrationSolution:

Check DAW architecture matches plugin (Intel vs Apple Silicon)
Verify plugin is code-signed: codesign -vv MyPlugin.component
Clear Audio Unit cache: killall -9 AudioComponentRegistrar
For AUv3: Run standalone app once to register

Build fails with SDK errors

Cause: Missing SDKs or incorrect pathsSolution:

Run Dependencies/download-iplug-sdks.sh

Check paths in common-mac.xcconfig:

VST3_SDK = $(DEPS_PATH)/IPlug/VST3_SDK
AAX_SDK = $(DEPS_PATH)/IPlug/AAX_SDK

Notarization fails

Cause: Hardened runtime not enabled or unsigned binariesSolution:

Sign with --options runtime flag
Ensure all frameworks and executables are signed

Check notarization log for details:

xcrun notarytool log <submission-id> \
  --apple-id [email protected] \
  --team-id TEAM_ID \
  --password app-specific-password

AUv3 not appearing in GarageBand/Logic

Cause: AUv3 not registered or code signing issueSolution:

Run standalone app at least once
Ensure app is properly code-signed (ad-hoc or Developer ID)
Check Console.app for errors
Verify entitlements are correct

Next Steps

iOS Build

Build AUv3 plugins for iOS

Code Signing

Deep dive into signing and notarization

CMake Build

Alternative build system

Installers

Create DMG installers

Getting Started

Core Concepts

IPlug Core

IGraphics

Alternative UI Frameworks

Building & Deployment

Guides

Advanced Topics

​Prerequisites

​Project Structure

​Building with Xcode

​Opening the Project

​Building in Xcode

​Building from Command Line

​Universal Binaries

Intel (x86_64)

Apple Silicon (arm64)

​Building Universal Binaries

​Verifying Universal Binaries

​Build Output

​Deployment Paths

​Customizing Deployment

​Code Signing

​Development Signing (Ad-hoc)

​Distribution Signing

​Notarization

​Using notarise.sh

​Debugging

​Setting Up Debugger

​LLDB Debugging

​Audio Unit Validation

​Common auval Errors

​Build Settings

​Common Settings (from common-mac.xcconfig)

​Preprocessor Defines

​Troubleshooting

​Next Steps

iOS Build

Code Signing

CMake Build

Installers

Build docs developers (and LLMs) love

Prerequisites

Project Structure

Building with Xcode

Opening the Project

Building in Xcode

Building from Command Line

Universal Binaries

Building Universal Binaries

Verifying Universal Binaries

Build Output

Deployment Paths

Customizing Deployment

Code Signing

Development Signing (Ad-hoc)

Distribution Signing

Notarization

Using notarise.sh

Debugging

Setting Up Debugger

LLDB Debugging

Audio Unit Validation

Common auval Errors

Build Settings

Common Settings (from common-mac.xcconfig)

Preprocessor Defines

Troubleshooting

Next Steps