annotate build/README.msvc @ 406:b7268e8bd292

Build tweaks for OS/X

The Vamp Plugin SDK -- Platform Notes for Visual C++ on Windows
===============================================================

Visual C++ Project Files
------------------------

Three Visual C++ project files are included with the SDK:

 - build/VampPluginSDK.vcproj

   This builds the plugin SDK into a single static library, but does
   not build the example plugins, the host SDK, or the host.  (We
   recommend using static linkage for the SDK rather than distributing
   it as a DLL, particularly when building plugins.)

 - build/VampHostSDK.vcproj

   This builds the host SDK into a single static library, but does not
   build the plugin SDK, example plugins, or host.

 - build/VampExamplePlugins.vcproj

   This builds the example plugins DLL, but does not build the plugin
   or host SDKs or the host.  You don't need to build the plugin SDK
   before this, because this project simply includes the plugin SDK
   files rather than using the library.

Of course, when using Visual Studio or another IDE to build a plugin
or host using the SDK, you may simply add the .h and .cpp files in the
vamp-sdk or vamp-hostsdk directories to your existing project.  This
is the approach taken in the VampExamplePlugins project.

As the command-line host has additional library dependencies (namely
libsndfile), no pre-packaged project is included to build it.


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

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

   build\release\vamp-example-plugins.dll
and
   examples\vamp-example-plugins.cat

to

   C:\Program Files\Vamp Plugins


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

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

One nice tidy way to achieve this with Visual Studio is to add the
linker option /EXPORT:vampGetPluginDescriptor to your project.  (All
of the other symbols will be properly hidden, because that is the
default for the Visual Studio linker.)  The included example plugins
project in build/VampExamplePlugins.vcproj does this.

Alternatively, you may modify vamp/vamp.h to add the
__declspec(dllexport) attribute to the vampGetPluginDescriptor
declaration.  This is not present by default, because it isn't
portable and, as we only want one symbol exported, the above linker
option works equally well without code changes.

(If you don't take at least one of these actions, your plugin library
simply will not load in any host.)


Using MinGW/Cygwin
------------------

Refer to README.linux for build instructions using the GNU toolchain.


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!