annotate build/README.osol @ 312:2ad57dd004ba

* Make plugin objects depend on headers as well as source files
* Note that we require GNU make
* Use non-recursive variable assignments throughout

The Vamp Plugin SDK -- Platform Notes for OpenSolaris with SunStudio Compilers
==============================================================================

Building at the command line
----------------------------

To build the SDK, example plugins, and command-line host using the
SunStudio C++ compiler (CC) with the Cstd standard library:

 $ make -f build/Makefile.osol

You must have libsndfile (http://www.mega-nerd.com/libsndfile/)
installed in order to build the command-line host successfully.  To
build only the SDK and examples:

 $ make -f build/Makefile.osol sdk examples

See the comments at the top of Makefile.osol for more information about
the libraries and other targets that are built in this way.

To install the libraries: 

 $ make -f build/Makefile.osol install

with the appropriate privileges (via pfexec or sudo).


Installing the Example Plugins
------------------------------

To install the example plugins so you can load them in Vamp hosts,
copy the files

   examples/vamp-example-plugins.so
and
   examples/vamp-example-plugins.cat

to
   /usr/local/lib/vamp/
or 
   $HOME/vamp/


Plugin Linkage
--------------

Vamp plugins are distributed as dynamic libraries (.so files).  A
properly packaged Vamp plugin library should export exactly one public
symbol, namely the Vamp API entry point vampGetPluginDescriptor.

The default for the Sun linker is to export all of the symbols in the
library.  This will work (the host will be able to load the plugin),
but it unnecessarily pollutes the host's symbol namespace, it may
cause symbol collisions in some esoteric circumstances, and it
increases the amount of time the plugin takes to load.

To improve this behaviour, you can instruct the linker to export only
the one required symbol using a linker script.  To do this, place the
text

{
	global: vampGetPluginDescriptor;
	local: *;
};

into a text file, and then use the -M mapfile option to the
linker to tell it to refer to this file.  All other symbols will then
be properly hidden.

The Makefile included in this SDK uses this method to manage symbol
visibility for the included example plugins, using the file
build/vamp-plugin.map.


Test Your Plugins
-----------------

The Vamp Plugin Tester is a vital utility which you can use to test
your plugins for common problems.  It can help you if you're having
problems getting your plugin to work at all, and you're strongly
advised to use it before you release anything.  Download it from the
Vamp plugins site now!