ndc plugs

Setting up XCode to Build a VST Plugin

Note: This tutorial is very likely out of date by now - it's probably only useful if you're still on OSX 10.3.

This is a simple walkthrough of the steps required to build a VST plugin using XCode on OS X. Any references to VSTGUI assume you're using the sourceforge version (which you should be anyway, it's a lot nicer), rather than the older version which comes with the 2.3 VST SDK. Wherever you see <PLUGIN_NAME>, replace it with the name of your plugin/XCode project.

Main Walkthrough

Start a new project (Carbon bundle).
Remove main.c, <PLUGIN_NAME>_Prefix.pch (Source) and InfoPlist.strings (Resources) files.
Go to 'Project->Edit Active Target '<PLUGIN_NAME>'', and select the 'Build' tab.
Point 'Header Search Paths' to the folder you've got the VST SDK in.
Change 'Wrapper Extension' from bundle to vst.
Change 'Installation Path' to $(HOME)/Library/Audio/Plug-Ins/VST/, or wherever you want the plugin installed to.
If you're using VSTGUI:
- Change 'Prefix Header' to <VSTGUI_PATH>/vstplugsquartz.h.
If you're not using VSTGUI:
- Change 'Prefix Header' to <VSTSDK_PATH>/source/common/vstplugsmacho.h.

<Optional>

'Properties'

Create a blank text file in the 'Resources' section, put BNDL???? in it, and save it as PkgInfo. This is to make sure the OS X Finder sees the plugin as an actual executable, and not just another folder of stuff (which is what a bundle is, really).
Go to 'Project->New Build Phase->New Shell Script Build Phase', and make sure the shell script appears at the end of the list of phases in the 'Targets-><PLUGIN_NAME>' part of the 'Groups & Files' section.
In the window that appears, put cp PkgInfo build/<PLUGIN_NAME>.vst/Contents/ in the Script editor. This is to make sure the PkgInfo file gets copied into the bundle.
Add another shell script, the same way as before, again making sure it appears at the end of the list.
In the window that appears, put cp -r build/<PLUGIN_NAME>.vst $HOME/Library/Audio/Plug-Ins/VST/ in the Script editor. This is is to copy the plugin over to your default plugins folder.
Add the plugin files and the common files from the VST SDK (as well as the VSTGUI files, if you're using it) to your project.

VSTGUI Notes

Add the ApplicationServices and Quicktime frameworks.
For any images you use, they must be named (i.e. the filename) very specifically:
bmp<RESOURCE_NUM>.bmp

Where <RESOURCE_NUM> is the resource number you've assigned them in your VSTGUI editor. The other thing to note is that the resource number in the filename must consist of 5 digits, so if you had a resource number of 100, the filename would be: bmp00100.bmp. This all applies to .png images as well (i.e. they have to be named like bmp00100.png, not png00100.png).

Configurations/Build Styles Notes

On the 'Build Results' window there's a drop down box named either 'Active Build Style' or 'Active Configuration', depending which version of XCode you're using. Setting this to Development means your plugin will be compiled with debug symbols etc. so you can debug it, while setting it to Deployment will compile it without debug symbols, and with optimisation. You can set which options apply to these build styles/configurations by ctrl-clicking the main project icon in the 'Groups & Files' section (it should be the first entry) and selecting 'Get Info'.

Debugging/Profiling Notes

If you want to debug your plugin, you'll have to set your host as a custom executable (after all you can't run a plugin without a host...). In the 'Project' menu, select 'New Custom Executable' and point it to your host. Now when you start the debugger, the host will start up, and you'll be able to debug your plugin.
If you're interested in optimising your plugin, make sure you check out Apple's Shark profiling tool. To get the latest version, you'll need to be an ADC member (it's free), and you can get it at the ADC member site (here). These are the steps you'll need to take to use it:
1. Set the 'Generate Profiling Code' option to true in your target's info window, and put -g-full in 'Other C Flags', so that Shark will be able to show you exactly which lines in your code are causing problems (note that you have to do it this way - as far as I can tell setting the 'Level of Debug Symbols' setting to full will not work).
2. Make sure you're in 'Deployment' mode, so Shark will be able to take account of any compiler optimisations.
3. Start your host, and get your plugin running. Start up Shark.
4. In Shark's window, set the combo boxes to (from left to right): Time Profile, Process, and the last one to the name of your host's process.
5. Still in Shark, press 'Start'. Shark will run for 30 secs, gathering data about your plugin.
6. When it finishes, Shark will open a new window with a list of symbols/functions, along with a percentage for each one (the relative time spent).
7. Locate an entry that belongs to your plugin, and double-click it. You will now see a listing of your code, with the lines where the most time is spent highlighted. Anywhere Shark sees a particular problem, it will display a button with a '!' - click it to get a suggestion on how to optimise it.