annotate build/README.osx @ 287:f3b1ba71a305

* When calculating timestamps in order to write them into features that
  previously lacked them, from a buffering adapter, we need to take into
  account any timestamp adjustment used by other wrappers that are being
  wrapped by this one (i.e. input domain adapter)

The Vamp Plugin SDK -- Platform Notes for OS/X
==============================================

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

To build the SDK, example plugins, and command-line host:

 $ make -f Makefile.osx

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 Makefile.osx sdk examples

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

If you are using an IDE, you may prefer to simply add the vamp-sdk and
src/vamp-sdk (for plugins) or vamp-hostsdk and src/vamp-hostsdk (for
hosts) directories to your existing project.


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

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

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

to
   /Library/Audio/Plug-Ins/Vamp/
or 
   $HOME/Library/Audio/Plug-Ins/Vamp/


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

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

The default for the OS/X 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 symbols list file.  To do this, place
the single line

_vampGetPluginDescriptor

(with leading underscore) into a text file, and then use the
-exported_symbols_list option to the linker to tell it to refer to
this file.  All other symbols will then be properly hidden.

The Makefile.osx included in this SDK uses this method to manage
symbol visibility for the included example plugins, using the file
build/vamp-plugin.list.  There are other methods that will work too,
but this one is simple and has the advantage of requiring no changes
to the code.