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