annotate README @ 64:e839338d3869 tip

Further Windows fix
author Chris Cannam
date Wed, 15 Apr 2020 16:30:40 +0100
parents 4154894d638c
children
rev   line source
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