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