Demolition is a destruction testing tool for LADSPA plugins. It's intended mostly for sanity checking your own code before you release it to the world. Demolition is a work in progress.

Build instructions

  1. Download a source tarball from my Linux audio page and untar it somewhere appropriate
  2. Go into the newly created directory and type make

No, there isn't any method to install demolition permanently yet. You can copy the binary demolition into your preferred place if you like. If the above instructions don't work, check you are using some relatively modern variant of a GNU/Linux system. Bug reports for non-Linux systems are likely to be discarded for now.

Using Demolition

Once the demolition binary is built you should be able to run it. By default Demolition will attempt to test all the plugins it can find in your LADSPA_PATH. If you'd rather test a single library, specify the full path to the library as an argument to demolition.

When running, Demolition is very verbose. You can capture all the output on your screen by redirecting file descriptor 5. For example if you use BASH as your shell you might use something like

demolition /usr/local/lib/ladspa/ 5> RESULTS

If you watch Demolition running you may see a plugin get stuck, perhaps in an infinite loop, and you can interrupt that plugin to get Demolition to move on to the next one by pressing Ctrl-C. Demolition uses a watchdog timer, so eventually the plugin will be killed by that instead.

Libraries are inspected one at a time, and plugins from the library are tested in order. Demolition will describe the plugin in a lot of detail, and already at this point errors may be reported. Errors in the plugin descriptor or the port descriptors are the most common reason for a plugin working in one host but not in others.

After the plugin description has been tested, Demolition will try testing the basic functionality of the plugin, calling all the functions defined by LADSPA, and then it runs a number of progressively more unpleasant data driven tests. Crashes, and to a certain extent even buffer xruns are detected and reported as errors, as are certain other conditions which are likely indicators of programmer error. Each test, and the subtests within it, are described just before they take place.

Demolition Errors

You can readily identify all errors reported by Demolition because they begin with the word ERROR. The vast majority of errors reported should be genuine code problems in your plugin. If you experience any errors which you believe are due to a problem in Demolition itself please double check before reporting the error. You may be tempted to ignore some errors, particularly those related to unusual or out-of-range values, but you should probably resist this temptation except for Watchdog timeouts. A plugin which runs progressively more slowly for large values of a particular control input is OK, so long as this is properly documented by the author. The Watchdog timeout is arbitrary (and at the time of writing can only be altered by changing the Demolition source) but it is needed to keep things moving along at a reasonable pace.

It's usually reasonable to assume that an error was caused by the subtest described just before it. In a few cases however, especially if the plugin under test erroneously preserves some state between instantiations, the underlying cause of the error may lie in an earlier subtest from the same test group, or even in an earlier test altogether. It is just possible (but very unlikely) that the error is caused by a previous plugin tested in the same run of Demolition.

If you can't figure out what's wrong from Demolition's description in combination with your own debugging techniques, or if you can't reproduce the problem very reliably, you will probably have to resort to reading Demolition's source sooner or later. Although the code is not heavily commented, it is broken up functionally according to the groups of tests. You should be able to find the relevant section of code by searching for the test name in main.c.