cannam@108: 
cannam@108: The Vamp Plugin SDK -- Platform Notes for Linux and other GNU platforms
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: $ ./configure
cannam@108: $ make
cannam@108: 
cannam@108: To install after a successful make, run "make install" as root (or via
cannam@108: sudo).
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.so
cannam@108: and
cannam@108:    examples/vamp-example-plugins.cat
cannam@108: 
cannam@108: to
cannam@108:    /usr/local/lib/vamp/
cannam@108: or 
cannam@108:    $HOME/vamp/
cannam@108: 
cannam@108: 
cannam@108: Plugin Linkage
cannam@108: --------------
cannam@108: 
cannam@108: Vamp plugins are distributed as dynamic libraries (.so files).  A
cannam@108: properly 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 GNU 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 linker script.  To do this, place the
cannam@108: text
cannam@108: 
cannam@108: {
cannam@108: 	global: vampGetPluginDescriptor;
cannam@108: 	local: *;
cannam@108: };
cannam@108: 
cannam@108: into a text file, and then use the --version-script option to the
cannam@108: linker to tell it to refer to this file.  All other symbols will then
cannam@108: be properly hidden.
cannam@108: 
cannam@108: The Makefile included in this SDK uses this method to manage symbol
cannam@108: visibility for the included example plugins, using the file
cannam@108: build/vamp-plugin.map.  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: