Chris@28
|
1
|
Chris@28
|
2 [Vamp] Plugin Load Checker
|
Chris@28
|
3 ==========================
|
Chris@28
|
4
|
Chris@28
|
5 This is a very small command-line program (C++98, no particular
|
Chris@28
|
6 dependencies) for testing plugin libraries to see if they are
|
Chris@28
|
7 loadable. You run the program, pass it a list of library paths to
|
Chris@28
|
8 stdin, it tries to load them, and it reports to stdout whether each
|
Chris@28
|
9 load succeeded or not.
|
Chris@28
|
10
|
Chris@28
|
11 The program was written for use with Vamp audio analysis plugins, but
|
Chris@28
|
12 it also works with other plugin formats. It has some hardcoded
|
Chris@28
|
13 knowledge of Vamp, LADSPA, and DSSI plugins but it can be used with
|
Chris@28
|
14 any plugins that involve loading DLLs and looking up descriptor
|
Chris@28
|
15 functions from them.
|
Chris@28
|
16
|
Chris@28
|
17 It comes with a library (C++11, Qt) that searches for candidate plugin
|
Chris@28
|
18 files for some known formats in standard locations and runs the
|
Chris@28
|
19 checker program as a separate process to check whether they can be
|
Chris@28
|
20 loaded. This can be used to scan plugins and blacklist any that might
|
Chris@29
|
21 crash a host on load.
|
Chris@28
|
22
|
Chris@28
|
23
|
Chris@28
|
24 About the command-line program
|
Chris@28
|
25 ------------------------------
|
Chris@28
|
26
|
Chris@28
|
27 The program (vamp-plugin-load-checker) accepts the name of a
|
Chris@28
|
28 descriptor symbol as its only command-line argument. It then reads a
|
Chris@28
|
29 list of plugin library paths from stdin, one per line. For each path
|
Chris@28
|
30 read, it attempts to load that library and retrieve the named
|
Chris@28
|
31 descriptor symbol, printing a line to stdout reporting whether this
|
Chris@28
|
32 was successful or not and then flushing stdout. The output line format
|
Chris@28
|
33 is described below. The program exits with code 0 if all libraries
|
Chris@28
|
34 were loaded successfully and non-zero otherwise.
|
Chris@28
|
35
|
Chris@28
|
36 Note that library paths must be ready to pass to dlopen() or
|
Chris@28
|
37 equivalent; this usually means they should be absolute paths.
|
Chris@28
|
38
|
Chris@28
|
39 Output line for successful load of library libname.so:
|
Chris@28
|
40 SUCCESS|/path/to/libname.so|
|
Chris@28
|
41
|
Chris@28
|
42 Output line for failed load of library libname.so:
|
Chris@28
|
43 FAILURE|/path/to/libname.so|Reason for failure if available
|
Chris@28
|
44
|
Chris@28
|
45 Although this program was written for use with Vamp audio analysis
|
Chris@28
|
46 plugins, it also works with other plugin formats. The program has some
|
Chris@28
|
47 hardcoded knowledge of Vamp, LADSPA, and DSSI plugins, but it can be
|
Chris@28
|
48 used with any plugins that involve loading DLLs and looking up
|
Chris@28
|
49 descriptor functions from them.
|
Chris@28
|
50
|
Chris@28
|
51 Sometimes plugins will crash completely on load, bringing down this
|
Chris@28
|
52 program with them. If the program exits before all listed plugins have
|
Chris@28
|
53 been checked, this means that the plugin following the last reported
|
Chris@28
|
54 one has crashed. Typically the caller may want to run it again,
|
Chris@28
|
55 omitting that plugin.
|
Chris@28
|
56
|
Chris@28
|
57 This program (src/helper.cpp) is written in C++98 and has no
|
Chris@28
|
58 particular dependencies apart from the dynamic loader library.
|
Chris@28
|
59
|
Chris@28
|
60
|
Chris@28
|
61 About the library
|
Chris@28
|
62 -----------------
|
Chris@28
|
63
|
Chris@28
|
64 Two C++ classes are provided for use by a host application:
|
Chris@28
|
65 PluginCandidates and KnownPlugins.
|
Chris@28
|
66
|
Chris@28
|
67 PluginCandidates knows how to invoke the checker program (if you
|
Chris@28
|
68 provide the path to it) and will do so for a set of plugin paths of
|
Chris@28
|
69 your request, returning success or failure reports to you.
|
Chris@28
|
70
|
Chris@28
|
71 KnownPlugins knows about a limited set of plugin formats (currently
|
Chris@28
|
72 Vamp, LADSPA, DSSI) and will use PluginCandidates to test all plugins
|
Chris@28
|
73 found in those formats' standard installation directories.
|
Chris@28
|
74
|
Chris@28
|
75 These are C++11 classes using the Qt toolkit.
|
Chris@28
|
76
|
Chris@28
|
77
|
Chris@28
|
78 How to compile
|
Chris@28
|
79 --------------
|
Chris@28
|
80
|
Chris@28
|
81 A Qt project (checker.pro) is provided, which compiles the program and
|
Chris@28
|
82 library:
|
Chris@28
|
83
|
Chris@28
|
84 $ qmake checker.pro
|
Chris@28
|
85 $ make
|
Chris@28
|
86
|
Chris@29
|
87 It also builds a program called checker-client which exercises the
|
Chris@29
|
88 library by using a KnownPlugins object with the program it just
|
Chris@29
|
89 compiled and printing out the results.
|
Chris@29
|
90
|
Chris@28
|
91 To compile only the command-line program, you should be able to use a
|
Chris@28
|
92 single C++ compiler invocation like:
|
Chris@28
|
93
|
Chris@28
|
94 $ c++ -o vamp-plugin-load-checker src/helper.cpp -ldl
|
Chris@28
|
95
|
Chris@28
|
96 I expect that most often the program and library will be compiled as
|
Chris@28
|
97 part of a larger host application. (They were written for use with
|
Chris@28
|
98 Sonic Visualiser.)
|
Chris@28
|
99
|
Chris@28
|
100
|
Chris@28
|
101 Copyright and licence
|
Chris@28
|
102 ---------------------
|
Chris@28
|
103
|
Chris@28
|
104 Written by Chris Cannam at the Centre for Digital Music, Queen Mary
|
Chris@28
|
105 University of London.
|
Chris@28
|
106
|
Chris@35
|
107 Copyright (c) 2016-2018 Queen Mary, University of London.
|
Chris@28
|
108
|
Chris@28
|
109 Permission is hereby granted, free of charge, to any person
|
Chris@28
|
110 obtaining a copy of this software and associated documentation
|
Chris@28
|
111 files (the "Software"), to deal in the Software without
|
Chris@28
|
112 restriction, including without limitation the rights to use, copy,
|
Chris@28
|
113 modify, merge, publish, distribute, sublicense, and/or sell copies
|
Chris@28
|
114 of the Software, and to permit persons to whom the Software is
|
Chris@28
|
115 furnished to do so, subject to the following conditions:
|
Chris@28
|
116
|
Chris@28
|
117 The above copyright notice and this permission notice shall be
|
Chris@28
|
118 included in all copies or substantial portions of the Software.
|
Chris@28
|
119
|
Chris@28
|
120 THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
|
Chris@28
|
121 EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
|
Chris@28
|
122 MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
|
Chris@28
|
123 NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY
|
Chris@28
|
124 CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF
|
Chris@28
|
125 CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
|
Chris@28
|
126 WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
|
Chris@28
|
127
|
Chris@28
|
128 Except as contained in this notice, the names of the Centre for
|
Chris@28
|
129 Digital Music and Queen Mary, University of London shall not be
|
Chris@28
|
130 used in advertising or otherwise to promote the sale, use or other
|
Chris@28
|
131 dealings in this Software without prior written authorization.
|
Chris@28
|
132
|