cannam@239: 
cannam@239: The Vamp Plugin SDK -- Platform Notes for OS/X
cannam@239: ==============================================
cannam@239: 
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@239:  $ make -f Makefile.osx
cannam@239: 
cannam@254: You must have libsndfile (http://www.mega-nerd.com/libsndfile/)
cannam@254: installed in order to build the command-line host successfully.  To
cannam@254: build only the SDK and examples:
cannam@239: 
cannam@239:  $ make -f 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: 
cannam@254: If you are using an IDE, you may prefer to simply add the vamp-sdk and
cannam@254: src/vamp-sdk (for plugins) or vamp-hostsdk and src/vamp-hostsdk (for
cannam@254: hosts) directories to your existing project.
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@239: Vamp plugins are distributed as dynamic libraries (.dylib).  A
cannam@239: 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: