annotate build/README.osx @ 433:f8a3bd2d86cb

Emscripten Makefile -- not done yet. Also need to factorise out all these common lists of source files.
author Chris Cannam
date Wed, 18 May 2016 16:15:09 +0100
parents 14b34e85523b
children 6dfe3dd38878
rev   line source
cannam@239 1
cannam@239 2 The Vamp Plugin SDK -- Platform Notes for OS/X
cannam@239 3 ==============================================
cannam@239 4
Chris@334 5 Prerequisites
Chris@334 6 -------------
Chris@334 7
Chris@397 8 You must have Xcode installed, with the command-line build tools (an
Chris@397 9 optional component).
Chris@334 10
Chris@334 11 You must have libsndfile (http://www.mega-nerd.com/libsndfile/)
Chris@334 12 installed in order to build the command-line host successfully. But
Chris@334 13 you do not need libsndfile if you only want to build plugins.
Chris@334 14
Chris@334 15
cannam@239 16 Building at the command line
cannam@239 17 ----------------------------
cannam@239 18
cannam@239 19 To build the SDK, example plugins, and command-line host:
cannam@239 20
cannam@291 21 $ make -f build/Makefile.osx
cannam@239 22
Chris@334 23 To build only the SDK and example plugins (for example if you do not
Chris@334 24 have libsndfile installed):
cannam@239 25
cannam@291 26 $ make -f build/Makefile.osx sdk examples
cannam@239 27
cannam@254 28 See the comments at the top of Makefile.osx for more information about
cannam@254 29 the libraries and other targets that are built in this way.
cannam@254 30
Chris@334 31 If you are using an IDE such as Xcode, you may prefer to simply add
Chris@334 32 the vamp-sdk and src/vamp-sdk (for plugins) or vamp-hostsdk and
Chris@334 33 src/vamp-hostsdk (for hosts) directories to your existing project.
Chris@334 34
Chris@397 35 If you are using OS/X 10.6 or older, you could try Makefile.osx.106
Chris@397 36 instead of Makefile.osx.
cannam@239 37
cannam@239 38
cannam@239 39 Installing the Example Plugins
cannam@239 40 ------------------------------
cannam@239 41
cannam@239 42 To install the example plugins so you can load them in Vamp hosts,
cannam@239 43 copy the files
cannam@239 44
cannam@239 45 examples/vamp-example-plugins.dylib
cannam@239 46 and
cannam@239 47 examples/vamp-example-plugins.cat
cannam@239 48
cannam@239 49 to
cannam@239 50 /Library/Audio/Plug-Ins/Vamp/
cannam@239 51 or
cannam@239 52 $HOME/Library/Audio/Plug-Ins/Vamp/
cannam@239 53
cannam@239 54
cannam@239 55 Plugin Linkage
cannam@239 56 --------------
cannam@239 57
cannam@292 58 Vamp plugins are distributed as dynamic libraries (.dylib). An OS/X
cannam@292 59 dynamic library has a formal installed name, which is recorded in the
cannam@292 60 library's header: you will need to ensure that this matches the
cannam@292 61 plugin's filename (e.g. vamp-example-plugins.dylib) by using the
cannam@292 62 -install_name <name> option at link time. The Makefile.osx provided
cannam@292 63 with the SDK contains an example of this.
cannam@292 64
cannam@292 65 A well-packaged Vamp plugin library should export exactly one public
cannam@239 66 symbol, namely the Vamp API entry point vampGetPluginDescriptor.
cannam@239 67
cannam@239 68 The default for the OS/X linker is to export all of the symbols in the
cannam@239 69 library. This will work (the host will be able to load the plugin),
cannam@239 70 but it unnecessarily pollutes the host's symbol namespace, it may
cannam@239 71 cause symbol collisions in some esoteric circumstances, and it
cannam@239 72 increases the amount of time the plugin takes to load.
cannam@239 73
cannam@239 74 To improve this behaviour, you can instruct the linker to export only
cannam@239 75 the one required symbol using a symbols list file. To do this, place
cannam@239 76 the single line
cannam@239 77
cannam@239 78 _vampGetPluginDescriptor
cannam@239 79
cannam@239 80 (with leading underscore) into a text file, and then use the
cannam@239 81 -exported_symbols_list option to the linker to tell it to refer to
cannam@239 82 this file. All other symbols will then be properly hidden.
cannam@239 83
cannam@239 84 The Makefile.osx included in this SDK uses this method to manage
cannam@239 85 symbol visibility for the included example plugins, using the file
cannam@239 86 build/vamp-plugin.list. There are other methods that will work too,
cannam@239 87 but this one is simple and has the advantage of requiring no changes
cannam@239 88 to the code.
cannam@239 89
cannam@291 90
cannam@291 91 Test Your Plugins
cannam@291 92 -----------------
cannam@291 93
cannam@291 94 The Vamp Plugin Tester is a vital utility which you can use to test
cannam@291 95 your plugins for common problems. It can help you if you're having
cannam@291 96 problems getting your plugin to work at all, and you're strongly
cannam@291 97 advised to use it before you release anything. Download it from the
cannam@291 98 Vamp plugins site now!
cannam@291 99