You should have at least a basic knowledge of C++, familiarity with git version control and be reasonably comfortable using the command line/terminal.

You need to have the followings hardware/tools installed:

• a real mac running macOS 10.13+ (YMMV). Virtual Machines aren't recommended, since GPU acceleration and audio will be emulated.
• an iOS device running iOS 14+ (YMMV). If you want to develop for iOS.
• Xcode 10 or higher
• Latest Git for macOS
• An Apple developer account. This is essential nowadays, for notarizing
• Python 3.x
• On macOS Monterey (macOS12), you will need to install php. You can do this via homebrew. brew install php

Other useful tools are:

• Visual Studio Code - A text editor that can be useful in addition to Xcode
• Reaper - You will need a DAW in which to test plug-ins that you build

It's good to keep your coding projects organised. In order to facilitate building complex projects for multiple platforms, iPlug2 has a well defined folder and project structure, which you are strongly advised to stick to. Advanced users may try to build iPlug2 with their build-system of choice (See also Out of Source Builds).

Personally I like to keep my programming projects in a sub-folder of my macOS user folder called Dev. e.g.

/Users/oli/Dev/iPlug2

The exact path is not important, but I'd advise a short path if possible without any spaces in the folder names. In order to set up iPlug2 in this location, first create the Dev folder in Finder. You can now clone the iPlug2 repo using git. You can also download a .zip file from here, but it's recommended that you clone using git in order to easily stay up to date with upstream changes.

$ git clone https://github.com/iPlug2/iPlug2.git

After it has checked-out the repository you will have the iPlug2 folder with the source code inside. We could jump in now and build an example, but if we want to build e.g. a VST3 plug-in we need to download the VST3 SDK and put it in the correct place for the iPlug2 projects to find it. iPlug2 includes some scripts to help with downloading of dependencies. NOTE: The AAX SDK and the VST2 SDK are not in the public domain, so if you want to build those formats you need to have access to those SDKs and place them in the iPlug2/Dependencies/IPlug folders manually.

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

The last line executes the script to download the VST3 SDK and put it in the correct place. Whilst we are here, we can also download some pre-built static libraries using another script, that may be useful at a later stage (for example if you want to try and use a different graphics-backend than the default).

$ cd iPlug2/Dependencies/
$ ./download-prebuilt-libs.sh

Note that the dependencies folders include README.md files which explain the contents of the folder.

The Examples folder contains many projects that you should now be able to compile. Let's open and compile the IPlugInstrument example.

$ cd iPlug2/Examples/IPlugInstrument
$ open IPlugInstrument.xcworkspace

This will open the Xcode workspace, which encapsulates two Xcode "Projects", one for macOS and one for iOS. If you are not interested in iOS development, you can delete that project from the workspace if you like. Each Xcode project features multiple "Targets" for the different plug-in formats that are supported on macOS or iOS. These targets are linked with "Schemes" which are what you use to choose which target to build. To start, let's build the macOS-APP scheme, which is a standalone application with audio and MIDI I/O. Select macOS-APP as the active scheme in the top right hand corner of the Xcode interface, then click the play icon or press Command-R to build and run the app.

You might get an error No account for team "686EDA2T8T". Add a new account in the Accounts preference pane or verify that your accounts have valid credentials. 686EDA2T8T is my Apple developer team ID. Unfortunately it is necessary for you to change this manually. You can do so in the "Signing & Capabilities page" for the target. You may need an apple developer account to get a team ID that lets you code sign app binaries that run on a real device.

Once, you have build the app and it is running, you may need to confirm some permissions on launch and change the Audio/MIDI settings in the preferences dialog in order to be able to play/hear anything.

Now you have built the app, try building a VST3 plug-in. Select the macOS-VST3 scheme in the active scheme menu and build it. If you don't have Reaper64 installed in /Applications, you can edit the scheme to choose a different debug executable.

Before we move on to making our own project, let's tweak the IPlugInstrument code slightly to prove we are building the plugin. Expand the IPlugInstrument-macOS project in the left hand pane in Xcode, and click IPlugInstrument.cpp to view it in the code editor. Find the plug-in constructor, which is the block of code towards the top of the file starting with IPlugInstrument::IPlugInstrument(const InstanceInfo& info){ /* ... */ }. The plug-in constructor is where your iPlug plug-in C++ class gets created. Lots of initialisation happens here, including setting up parameters, presets and laying out the user interface. Let's change the background color from gray to white.

Find the following line of code (around line 27):

pGraphics->AttachPanelBackground(COLOR_GRAY);

and change COLOR_GRAY to COLOR_WHITE

Now rebuild the project and you should see that the background has changed to white.

All the iPlug2 example projects can be used as templates for new projects. A python script "duplicate.py" is used to clone a project folder doing a multi-file find and replace to change all occurrences of the template name with the new name.

In this case, we will create project called MyNewPlugin based on the IPlugEffect project, which is the simplest iPlug2 example - just a volume control. The following commands can be used to do that. You can replace MyManufacturerName with your company name, which should not include spaces.

$ cd iPlug2/Examples
python duplicate.py IPlugEffect MyNewPlugin MyManufacturerName

Now we have a new folder MyNewPlugin, with Xcode projects (and Visual Studio projects for windows) already set up so we can compile straight away. Before we do that though, let's initialise a git repository for our new project, add all the files and make an initial commit.

$ cd iPlug2/Examples/MyNewPlugin 
git init .
git add *
git commit -m "initial commit"

Now everything is under version control, any changes can be reverted, which is a very useful thing! We could now go and create a repository at github (or similar) for our project, and add it as a remote, so we can store and manage the project "in the cloud". This is convenient if we need to check out the repo and build it elsewhere.

You should now open your new project...

$ cd iPlug2/Examples/MyNewPlugin
$ open MyNewPlugin.xcworkspace

It's important that the project has the same relationship to the rest of the iPlug2 source code, but it doesn't have to be in the Examples folder. Typically for my own projects I make a folder parallel to Examples called Projects.

You now know the basics of setting up iPlug2 on macOS. :-)

To build for iOS the process is much the same. Select the iOS-APP with AUv3 scheme and build it. In order to install it on a device you will need to have an Apple developer account set up, and you will need to select your "Team" in the "Signing & Capabilities" panel for each of the targets in the iOS Xcode project.

If you want to build the AUv3 target on and debug your AUv3 on the iOS simulator, you need to have a host on the simulator. Since you can’t get e.g. Garageband or AUM on the simulator, your best bet is to build the Apple AUv3 hosting example and use that.