Mercurial > hg > vamp-plugin-load-checker

changeset 28:7a20698b4c29

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Add checker README; rename plugin-checker-helper binary (back) to vamp-plugin-load-checker -- I decided it was more useful to have a distinctive name for the installed binary than it was important to show that it was plugin-agnostic
author Chris Cannam
date Mon, 09 Jan 2017 10:14:59 +0000
parents 62a0cda8b099
children e791c1426131
files .hgignore README checker/knownplugins.h helper.pro src/checker.cpp src/helper.cpp
diffstat 6 files changed, 152 insertions(+), 6 deletions(-) [+]
line wrap: on
line diff
--- a/.hgignore	Sun Jan 08 16:09:47 2017 +0000
+++ b/.hgignore	Mon Jan 09 10:14:59 2017 +0000
@@ -5,3 +5,4 @@
 Makefile*
 checker-client
 plugin-checker-helper
+vamp-plugin-load-checker
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/README	Mon Jan 09 10:14:59 2017 +0000
@@ -0,0 +1,128 @@
+
+[Vamp] Plugin Load Checker
+==========================
+
+This is a very small command-line program (C++98, no particular
+dependencies) for testing plugin libraries to see if they are
+loadable. You run the program, pass it a list of library paths to
+stdin, it tries to load them, and it reports to stdout whether each
+load succeeded or not.
+
+The program was written for use with Vamp audio analysis plugins, but
+it also works with other plugin formats. It has some hardcoded
+knowledge of Vamp, LADSPA, and DSSI plugins but it can be used with
+any plugins that involve loading DLLs and looking up descriptor
+functions from them.
+
+It comes with a library (C++11, Qt) that searches for candidate plugin
+files for some known formats in standard locations and runs the
+checker program as a separate process to check whether they can be
+loaded. This can be used to scan plugins and blacklist any that might
+crash the host on load.
+
+
+About the command-line program
+------------------------------
+
+The program (vamp-plugin-load-checker) accepts the name of a
+descriptor symbol as its only command-line argument. It then reads a
+list of plugin library paths from stdin, one per line. For each path
+read, it attempts to load that library and retrieve the named
+descriptor symbol, printing a line to stdout reporting whether this
+was successful or not and then flushing stdout. The output line format
+is described below. The program exits with code 0 if all libraries
+were loaded successfully and non-zero otherwise.
+
+Note that library paths must be ready to pass to dlopen() or
+equivalent; this usually means they should be absolute paths.
+
+Output line for successful load of library libname.so:
+SUCCESS|/path/to/libname.so|
+
+Output line for failed load of library libname.so:
+FAILURE|/path/to/libname.so|Reason for failure if available
+
+Although this program was written for use with Vamp audio analysis
+plugins, it also works with other plugin formats. The program has some
+hardcoded knowledge of Vamp, LADSPA, and DSSI plugins, but it can be
+used with any plugins that involve loading DLLs and looking up
+descriptor functions from them.
+
+Sometimes plugins will crash completely on load, bringing down this
+program with them. If the program exits before all listed plugins have
+been checked, this means that the plugin following the last reported
+one has crashed. Typically the caller may want to run it again,
+omitting that plugin.
+
+This program (src/helper.cpp) is written in C++98 and has no
+particular dependencies apart from the dynamic loader library.
+
+
+About the library
+-----------------
+
+Two C++ classes are provided for use by a host application:
+PluginCandidates and KnownPlugins.
+
+PluginCandidates knows how to invoke the checker program (if you
+provide the path to it) and will do so for a set of plugin paths of
+your request, returning success or failure reports to you.
+
+KnownPlugins knows about a limited set of plugin formats (currently
+Vamp, LADSPA, DSSI) and will use PluginCandidates to test all plugins
+found in those formats' standard installation directories.
+
+These are C++11 classes using the Qt toolkit.
+
+
+How to compile
+--------------
+
+A Qt project (checker.pro) is provided, which compiles the program and
+library:
+
+$ qmake checker.pro
+$ make
+
+To compile only the command-line program, you should be able to use a
+single C++ compiler invocation like:
+
+$ c++ -o vamp-plugin-load-checker src/helper.cpp -ldl
+
+I expect that most often the program and library will be compiled as
+part of a larger host application. (They were written for use with
+Sonic Visualiser.)
+
+
+Copyright and licence
+---------------------
+
+Written by Chris Cannam at the Centre for Digital Music, Queen Mary
+University of London.
+
+    Copyright (c) 2016-2017 Queen Mary, University of London.
+
+    Permission is hereby granted, free of charge, to any person
+    obtaining a copy of this software and associated documentation
+    files (the "Software"), to deal in the Software without
+    restriction, including without limitation the rights to use, copy,
+    modify, merge, publish, distribute, sublicense, and/or sell copies
+    of the Software, and to permit persons to whom the Software is
+    furnished to do so, subject to the following conditions:
+
+    The above copyright notice and this permission notice shall be
+    included in all copies or substantial portions of the Software.
+
+    THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
+    EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
+    MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
+    NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR ANY
+    CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF
+    CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
+    WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+
+    Except as contained in this notice, the names of the Centre for
+    Digital Music and Queen Mary, University of London shall not be
+    used in advertising or otherwise to promote the sale, use or other
+    dealings in this Software without prior written authorization.
+
--- a/checker/knownplugins.h	Sun Jan 08 16:09:47 2017 +0000
+++ b/checker/knownplugins.h	Mon Jan 09 10:14:59 2017 +0000
@@ -36,6 +36,15 @@
 #include <map>
 #include <vector>
 
+/**
+ * Class to identify and list candidate shared-library files possibly
+ * containing plugins in a hardcoded set of known formats. Uses a
+ * separate process (the "helper", whose executable name must be
+ * provided at construction) to test-load each library in order to
+ * winnow out any that fail to load or crash on load.
+ *
+ * Requires C++11 and the Qt5 QtCore library.
+ */
 class KnownPlugins
 {
     typedef std::vector<std::string> stringlist;
--- a/helper.pro	Sun Jan 08 16:09:47 2017 +0000
+++ b/helper.pro	Mon Jan 09 10:14:59 2017 +0000
@@ -18,7 +18,7 @@
     QMAKE_LFLAGS += -ldl
 }
 
-TARGET = plugin-checker-helper
+TARGET = vamp-plugin-load-checker
 
 OBJECTS_DIR = o
 MOC_DIR = o
--- a/src/checker.cpp	Sun Jan 08 16:09:47 2017 +0000
+++ b/src/checker.cpp	Mon Jan 09 10:14:59 2017 +0000
@@ -42,7 +42,7 @@
 int main(int, char **)
 {
     LogCallback cb;
-    KnownPlugins kp("./plugin-checker-helper", &cb); //!!!
+    KnownPlugins kp("./vamp-plugin-load-checker", &cb);
     
     for (auto t: kp.getKnownPluginTypes()) {
         cout << "successful libraries for plugin type \""
--- a/src/helper.cpp	Sun Jan 08 16:09:47 2017 +0000
+++ b/src/helper.cpp	Mon Jan 09 10:14:59 2017 +0000
@@ -1,7 +1,7 @@
 /* -*- c-basic-offset: 4 indent-tabs-mode: nil -*-  vi:set ts=8 sts=4 sw=4: */
 
 /**
- * Plugin Load Checker Helper
+ * [Vamp] Plugin Load Checker
  *
  * This program accepts the name of a descriptor symbol as its only
  * command-line argument. It then reads a list of plugin library paths
@@ -21,6 +21,12 @@
  * Output line for failed load of library libname.so:
  * FAILURE|/path/to/libname.so|Reason for failure if available
  *
+ * Although this program was written for use with Vamp audio analysis
+ * plugins, it also works with other plugin formats. The program has
+ * some hardcoded knowledge of Vamp, LADSPA, and DSSI plugins, but it
+ * can be used with any plugins that involve loading DLLs and looking
+ * up descriptor functions from them.
+ *
  * Sometimes plugins will crash completely on load, bringing down this
  * program with them. If the program exits before all listed plugins
  * have been checked, this means that the plugin following the last
@@ -29,7 +35,7 @@
  */
 
 /*
-    Copyright (c) 2016 Queen Mary, University of London
+    Copyright (c) 2016-2017 Queen Mary, University of London
 
     Permission is hereby granted, free of charge, to any person
     obtaining a copy of this software and associated documentation
@@ -58,6 +64,8 @@
 
 #include "../version.h"
 
+static const char programName[] = "vamp-plugin-load-checker";
+
 #ifdef _WIN32
 #include <windows.h>
 #include <process.h>
@@ -209,9 +217,9 @@
     
     if (argc != 2 || showUsage) {
         cerr << endl;
-        cerr << "plugin-checker-helper: Test shared library objects for plugins to be" << endl;
+        cerr << programName << ": Test shared library objects for plugins to be" << endl;
         cerr << "loaded via descriptor functions." << endl;
-        cerr << "\n    Usage: plugin-checker-helper <descriptorname>\n"
+        cerr << "\n    Usage: " << programName << " <descriptorname>\n"
             "\nwhere descriptorname is the name of a plugin descriptor symbol to be sought\n"
             "in each library (e.g. vampGetPluginDescriptor for Vamp plugins). The list of\n"
             "candidate plugin library filenames is read from stdin.\n" << endl;