Definition
The namespace prefix <tt>lv2:</tt> in this document expands to the uri http://lv2plug.in/ns/lv2core#
An LV2 Bundle is a directory (or equivalent, such as an archive) containing the file <tt>manifest.ttl</tt> at the top level, which is RDF data in the Turtle syntax. The semantics of the mandatory RDF data is defined in lv2.ttl.
- All information necessary for a host to discover (but not necessarily use) the contents of a bundle (plugins, extensions, etc.) MUST be present in <tt>manifest.ttl</tt>
- The host can discover which plugins are present by scanning <tt>manifest.ttl</tt> for triples of the form <pre><plugin-uri> a lv2:Plugin .</pre> and discover all data files for each plugin via triples of the form <pre><plugin-uri> rdfs:seeAlso <datafile.ttl> .</pre>
- The description of a plugin (or any other LV2 resource) may be split across several bundles. Hosts SHOULD scan the manifest of all installed bundles first, then load plugin data from all discovered data files for that plugin.
- If a <tt>manifest.ttl</tt> contains the triple <pre><extension-uri> a lv2:Specification .</pre> the host SHOULD consider any data in that <tt>manifest.ttl</tt> and all files related via triples of the form <pre><extension-uri> rdfs:seeAlso <datafile.ttl> .</pre> as if they were part of lv2.ttl itself. For example, if such a specification defines additional plugin classes, hosts SHOULD include those classes in their plugin class hierarchy (e.g. for menus).
- If a host finds insufficient information in a bundle which it understands (or is interested in), the host MAY simply ignore the bundle
Installation
- The name of a bundle itself MUST NOT be given any long-term significance by hosts (e.g. in save files).
- Hosts may include special plugin bundles as part of their installation and depend on the existence of those bundles to find certain plugins, but references to the plugins themselves should still be serialized by plugin URI and the normal discovery mechanism used.
- Users MUST be able to rename installed bundle directories without any save files breaking.
- Extensions MUST NOT define "special" bundle names (eg by adding a suffix to the plugin bundle name) for discovery purposes.
- Instead, things should be related in RDF (e.g. with rdfs:seeAlso)
- Defining certain paths (i.e. things to be included in LV2_PATH) which contain bundles for specific uses is fine.
Discovery
- If a host encounters a bundle it does not "understand" or care about, it SHOULD simply ignore it.
- Hosts SHOULD consider all data files associated with a plugin (including the <tt>manifest.ttl</tt> file that contains the <pre><plugin-uri> a lv2:Plugin</pre> triple for that plugin) whenever looking for information about a plugin.
- In other words, hosts should discover all installed LV2 bundles before investigating any plugins.
- SPARQL translation: whenever querying a plugin, hosts should SELECT FROM lv2.ttl, all discovered LV2 extension files, and all discovered plugin data files (as defined above).
Individual Bundle Contents
Note that <tt>manifest.ttl</tt> can (intrinsically) contain information about any number of things. One bundle can contain several plugins, several extensions, and several implementations of extensions for those plugins, however in usual cases it is a bad idea and authors should use common sense and follow the existing precedent as closely as possible.
Including a large number of unrelated plugins or extensions in a single bundle is strongly discouraged. The best practice is to either include a single plugin per bundle, or variants of the "same" plugin in a bundle (and any included extension implementations for it etc. etc.). Users should be able to manage their plugin collections by renaming or moving bundle directories with a file manager - consider this when deciding what to put in your bundles.
Plugin developers should not ruin the user's ability to manage their plugin collections by bundling too many unrelated plugins together'''
Examples
Plugin Bundle
A bundle which contains one or more LV2 plugin(s)
- <tt>manifest.ttl</tt> contains the triple <pre><pluginuri> a lv2:Plugin .</pre>
- <tt>manifest.ttl</tt> MAY contain triples of the form <pre><pluginuri> rdfs:seeAlso <datafile.ttl> .</pre> meaning the host SHOULD consider <tt>datafile.ttl</tt> a part of the data that defines the plugin.
LV2 Extension Bundle
A bundle which contains an extension to the LV2 specification
- <tt>manifest.ttl</tt> contains the triple <pre><extensionuri> a lv2:Specification .</pre>
- manifest.ttl MAY contain triples of the form <pre><extensionuri> rdfs:seeAlso <datafile.ttl> .</pre> meaning the host should treat the contents of <tt>datafile.ttl</tt> as part of the LV2 specification (as if the data was included in <tt>lv2.ttl</tt> itself)
- Hosts SHOULD use all of this data as their LV2 specification (not just <tt>lv2.ttl</tt>)
- Rationale: new categories, port types, etc. Just Work, and plugin/extension relationships can possibly do new things without explicitly implementing host logic for that particular extension).
Plugin Extension Bundle
A bundle which contains the implementation of an LV2 extension for a (possibly separate) plugin
- <tt>manifest.ttl</tt> contains the triple <pre><pluginuri> rdfs:seeAlso <foo.ttl> .</pre> where foo.ttl contains any information necessary to discover and use the extension implementation (as defined by the LV2 extension)
- Hosts SHOULD include <tt>foo.ttl</tt> as part of the plugin's data, as if the contents of <tt>foo.ttl</tt> are included in the plugin's data file itself.
- Example: a GUI extension (prefix guiext:) that defines a shared object file implementing a GUI for a plugin could define a predicate <tt>guiext:guiBinary</tt>, so <tt>manifest.ttl</tt> of a bundle implementing this type of GUI for the plugin with URI <somepluginuri> contains the triples
<somepluginuri> rdfs:seeAlso <> . <somepluginuri> guiext:guiBinary <guibinary.so> .
if the data is in <tt>manifest.ttl</tt>, or
<somepluginuri> rdfs:seeAlso <someplugingui.ttl> .
if the data is in <tt>someplugingui.ttl</tt> in the top level of the bundle directory. That file would then contain the triple
<somepluginuri> guiext:guiBinary <guibinary.so> .
