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