Chris@12: 
Chris@12: The Vamp Plugin SDK -- Platform Notes for Linux and other GNU platforms
Chris@12: =======================================================================
Chris@12: 
Chris@12: Building at the command line
Chris@12: ----------------------------
Chris@12: 
Chris@12: To build the SDK, example plugins, and command-line host:
Chris@12: 
Chris@12: $ ./configure
Chris@12: $ make
Chris@12: 
Chris@12: To install after a successful make, run "make install" as root (or via
Chris@12: sudo).
Chris@12: 
Chris@12: 
Chris@12: Installing the Example Plugins
Chris@12: ------------------------------
Chris@12: 
Chris@12: To install the example plugins so you can load them in Vamp hosts,
Chris@12: copy the files
Chris@12: 
Chris@12:    examples/vamp-example-plugins.so
Chris@12: and
Chris@12:    examples/vamp-example-plugins.cat
Chris@12: 
Chris@12: to
Chris@12:    /usr/local/lib/vamp/
Chris@12: or 
Chris@12:    $HOME/vamp/
Chris@12: 
Chris@12: 
Chris@12: Plugin Linkage
Chris@12: --------------
Chris@12: 
Chris@12: Vamp plugins are distributed as dynamic libraries (.so files).  A
Chris@12: properly packaged Vamp plugin library should export exactly one public
Chris@12: symbol, namely the Vamp API entry point vampGetPluginDescriptor.
Chris@12: 
Chris@12: The default for the GNU linker is to export all of the symbols in the
Chris@12: library.  This will work (the host will be able to load the plugin),
Chris@12: but it unnecessarily pollutes the host's symbol namespace, it may
Chris@12: cause symbol collisions in some esoteric circumstances, and it
Chris@12: increases the amount of time the plugin takes to load.
Chris@12: 
Chris@12: To improve this behaviour, you can instruct the linker to export only
Chris@12: the one required symbol using a linker script.  To do this, place the
Chris@12: text
Chris@12: 
Chris@12: {
Chris@12: 	global: vampGetPluginDescriptor;
Chris@12: 	local: *;
Chris@12: };
Chris@12: 
Chris@12: into a text file, and then use the --version-script option to the
Chris@12: linker to tell it to refer to this file.  All other symbols will then
Chris@12: be properly hidden.
Chris@12: 
Chris@12: The Makefile included in this SDK uses this method to manage symbol
Chris@12: visibility for the included example plugins, using the file
Chris@12: build/vamp-plugin.map.  There are other methods that will work too,
Chris@12: but this one is simple and has the advantage of requiring no changes
Chris@12: to the code.
Chris@12: 
Chris@12: 
Chris@12: Test Your Plugins
Chris@12: -----------------
Chris@12: 
Chris@12: The Vamp Plugin Tester is a vital utility which you can use to test
Chris@12: your plugins for common problems.  It can help you if you're having
Chris@12: problems getting your plugin to work at all, and you're strongly
Chris@12: advised to use it before you release anything.  Download it from the
Chris@12: Vamp plugins site now!
Chris@12: