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