cannam@291: 
cannam@291: The Vamp Plugin SDK -- Platform Notes for OpenSolaris with SunStudio Compilers
cannam@291: ==============================================================================
cannam@291: 
cannam@291: Building at the command line
cannam@291: ----------------------------
cannam@291: 
cannam@291: To build the SDK, example plugins, and command-line host using the
cannam@291: SunStudio C++ compiler (CC) with the Cstd standard library:
cannam@291: 
cannam@291:  $ make -f build/Makefile.osol
cannam@291: 
cannam@291: You must have libsndfile (http://www.mega-nerd.com/libsndfile/)
cannam@291: installed in order to build the command-line host successfully.  To
cannam@291: build only the SDK and examples:
cannam@291: 
cannam@291:  $ make -f build/Makefile.osol sdk examples
cannam@291: 
cannam@291: See the comments at the top of Makefile.osol for more information about
cannam@291: the libraries and other targets that are built in this way.
cannam@291: 
cannam@291: To install the libraries: 
cannam@291: 
cannam@291:  $ make -f build/Makefile.osol install
cannam@291: 
cannam@291: with the appropriate privileges (via pfexec or sudo).
cannam@291: 
cannam@291: 
cannam@291: Installing the Example Plugins
cannam@291: ------------------------------
cannam@291: 
cannam@291: To install the example plugins so you can load them in Vamp hosts,
cannam@291: copy the files
cannam@291: 
cannam@291:    examples/vamp-example-plugins.so
cannam@291: and
cannam@291:    examples/vamp-example-plugins.cat
cannam@291: 
cannam@291: to
cannam@291:    /usr/local/lib/vamp/
cannam@291: or 
cannam@291:    $HOME/vamp/
cannam@291: 
cannam@291: 
cannam@291: Plugin Linkage
cannam@291: --------------
cannam@291: 
cannam@291: Vamp plugins are distributed as dynamic libraries (.so files).  A
cannam@291: properly packaged Vamp plugin library should export exactly one public
cannam@291: symbol, namely the Vamp API entry point vampGetPluginDescriptor.
cannam@291: 
cannam@291: The default for the Sun linker is to export all of the symbols in the
cannam@291: library.  This will work (the host will be able to load the plugin),
cannam@291: but it unnecessarily pollutes the host's symbol namespace, it may
cannam@291: cause symbol collisions in some esoteric circumstances, and it
cannam@291: increases the amount of time the plugin takes to load.
cannam@291: 
cannam@291: To improve this behaviour, you can instruct the linker to export only
cannam@291: the one required symbol using a linker script.  To do this, place the
cannam@291: text
cannam@291: 
cannam@291: {
cannam@291: 	global: vampGetPluginDescriptor;
cannam@291: 	local: *;
cannam@291: };
cannam@291: 
cannam@291: into a text file, and then use the -M mapfile option to the
cannam@291: linker to tell it to refer to this file.  All other symbols will then
cannam@291: be properly hidden.
cannam@291: 
cannam@291: The Makefile included in this SDK uses this method to manage symbol
cannam@291: visibility for the included example plugins, using the file
cannam@291: build/vamp-plugin.map.
cannam@291: 
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: