diff build/README.osol @ 291:2e16d99867bd

* Tidying, build, versions, docs updates for release

--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/build/README.osol	Tue Sep 22 10:02:56 2009 +0000
@@ -0,0 +1,84 @@
+
+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!
+