comparison src/vamp-plugin-sdk-2.4/build/README.osx @ 12:b7bda433d832

Add Vamp SDK source

+
+The Vamp Plugin SDK -- Platform Notes for OS/X
+==============================================
+
+Prerequisites
+-------------
+
+You must have Xcode installed, with the command-line build tools.
+
+(If you are using Xcode 4, you may have to go to Preferences ->
+Downloads -> Components and install the Command Line Tools component.)
+
+You must have libsndfile (http://www.mega-nerd.com/libsndfile/)
+installed in order to build the command-line host successfully.  But
+you do not need libsndfile if you only want to build plugins.
+
+
+Building at the command line
+----------------------------
+
+To build the SDK, example plugins, and command-line host:
+
+ $ make -f build/Makefile.osx
+
+To build only the SDK and example plugins (for example if you do not
+have libsndfile installed):
+
+ $ make -f build/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 such as Xcode, 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.
+
+If you are using OS/X 10.6 or older, use Makefile.osx.106 instead of
+Makefile.osx.
+
+
+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).  An OS/X
+dynamic library has a formal installed name, which is recorded in the
+library's header: you will need to ensure that this matches the
+plugin's filename (e.g. vamp-example-plugins.dylib) by using the
+-install_name <name> option at link time.  The Makefile.osx provided
+with the SDK contains an example of this.
+
+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.
+
+
+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!
+