cannam@108: 
cannam@108: The Vamp Plugin SDK -- Platform Notes for OS/X
cannam@108: ==============================================
cannam@108: 
cannam@108: Prerequisites
cannam@108: -------------
cannam@108: 
cannam@108: You must have Xcode installed, with the command-line build tools.
cannam@108: 
cannam@108: (If you are using Xcode 4, you may have to go to Preferences ->
cannam@108: Downloads -> Components and install the Command Line Tools component.)
cannam@108: 
cannam@108: You must have libsndfile (http://www.mega-nerd.com/libsndfile/)
cannam@108: installed in order to build the command-line host successfully.  But
cannam@108: you do not need libsndfile if you only want to build plugins.
cannam@108: 
cannam@108: 
cannam@108: Building at the command line
cannam@108: ----------------------------
cannam@108: 
cannam@108: To build the SDK, example plugins, and command-line host:
cannam@108: 
cannam@108:  $ make -f build/Makefile.osx
cannam@108: 
cannam@108: To build only the SDK and example plugins (for example if you do not
cannam@108: have libsndfile installed):
cannam@108: 
cannam@108:  $ make -f build/Makefile.osx sdk examples
cannam@108: 
cannam@108: See the comments at the top of Makefile.osx for more information about
cannam@108: the libraries and other targets that are built in this way.
cannam@108: 
cannam@108: If you are using an IDE such as Xcode, you may prefer to simply add
cannam@108: the vamp-sdk and src/vamp-sdk (for plugins) or vamp-hostsdk and
cannam@108: src/vamp-hostsdk (for hosts) directories to your existing project.
cannam@108: 
cannam@108: If you are using OS/X 10.6 or older, use Makefile.osx.106 instead of
cannam@108: Makefile.osx.
cannam@108: 
cannam@108: 
cannam@108: Installing the Example Plugins
cannam@108: ------------------------------
cannam@108: 
cannam@108: To install the example plugins so you can load them in Vamp hosts,
cannam@108: copy the files
cannam@108: 
cannam@108:    examples/vamp-example-plugins.dylib
cannam@108: and
cannam@108:    examples/vamp-example-plugins.cat
cannam@108: 
cannam@108: to
cannam@108:    /Library/Audio/Plug-Ins/Vamp/
cannam@108: or 
cannam@108:    $HOME/Library/Audio/Plug-Ins/Vamp/
cannam@108: 
cannam@108: 
cannam@108: Plugin Linkage
cannam@108: --------------
cannam@108: 
cannam@108: Vamp plugins are distributed as dynamic libraries (.dylib).  An OS/X
cannam@108: dynamic library has a formal installed name, which is recorded in the
cannam@108: library's header: you will need to ensure that this matches the
cannam@108: plugin's filename (e.g. vamp-example-plugins.dylib) by using the
cannam@108: -install_name <name> option at link time.  The Makefile.osx provided
cannam@108: with the SDK contains an example of this.
cannam@108: 
cannam@108: A well-packaged Vamp plugin library should export exactly one public
cannam@108: symbol, namely the Vamp API entry point vampGetPluginDescriptor.
cannam@108: 
cannam@108: The default for the OS/X linker is to export all of the symbols in the
cannam@108: library.  This will work (the host will be able to load the plugin),
cannam@108: but it unnecessarily pollutes the host's symbol namespace, it may
cannam@108: cause symbol collisions in some esoteric circumstances, and it
cannam@108: increases the amount of time the plugin takes to load.
cannam@108: 
cannam@108: To improve this behaviour, you can instruct the linker to export only
cannam@108: the one required symbol using a symbols list file.  To do this, place
cannam@108: the single line
cannam@108: 
cannam@108: _vampGetPluginDescriptor
cannam@108: 
cannam@108: (with leading underscore) into a text file, and then use the
cannam@108: -exported_symbols_list option to the linker to tell it to refer to
cannam@108: this file.  All other symbols will then be properly hidden.
cannam@108: 
cannam@108: The Makefile.osx included in this SDK uses this method to manage
cannam@108: symbol visibility for the included example plugins, using the file
cannam@108: build/vamp-plugin.list.  There are other methods that will work too,
cannam@108: but this one is simple and has the advantage of requiring no changes
cannam@108: to the code.
cannam@108: 
cannam@108: 
cannam@108: Test Your Plugins
cannam@108: -----------------
cannam@108: 
cannam@108: The Vamp Plugin Tester is a vital utility which you can use to test
cannam@108: your plugins for common problems.  It can help you if you're having
cannam@108: problems getting your plugin to work at all, and you're strongly
cannam@108: advised to use it before you release anything.  Download it from the
cannam@108: Vamp plugins site now!
cannam@108: