Bundle Definition
From Lv2
Contents |
[edit] Definition
The namespace prefix lv2: 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 manifest.ttl at the top level, which is RDF data in the Turtle syntax. The semantics of the mandatory RDF data is defined in the file 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 manifest.ttl
- After reading all bundles' manifest.ttl files, a host knows which plugins are present via triples of the form
<plugin-uri> a lv2:Plugin .
and all data files associated with each plugin via triples of the form<plugin-uri> rdfs:seeAlso <datafile.ttl> .
which could come from any bundle (i.e. not just the plugin's bundle) - When investigating or using a plugin, hosts are expected to use the contents of manifest.ttl itself, and traverse all of these rdfs:seeAlso links at least one level deep to find the necessary information
- If any manifest.ttl contains the triple
<extensionuri> a lv2:Specification .
the host should consider any data in that file and other files in that bundle referenced with<extensionuri> rdfs:seeAlso <datafile.ttl> .
as if it was defined in lv2.ttl.
- After reading all bundles' manifest.ttl files, a host knows which plugins are present via triples of the form
- If a host finds insufficient information in a bundle which it understands (or is interested in), the host MAY simply ignore the bundle
[edit] 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.
[edit] 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 manifest.ttl file that contains the
<plugin-uri> a lv2:Plugin
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).
[edit] Individual Bundle Contents
Note that manifest.ttl 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!
[edit] Examples
[edit] Plugin Bundle
A bundle which contains one or more LV2 plugin(s)
- manifest.ttl contains the triple
<pluginuri> a lv2:Plugin .
- manifest.ttl MAY contain triples of the form
<pluginuri> rdfs:seeAlso <datafile.ttl> .
meaning the host SHOULD consider datafile.ttl a part of the data that defines the plugin.
[edit] LV2 Extension Bundle
A bundle which contains an extension to the LV2 specification
- manifest.ttl contains the triple
<extensionuri> a lv2:Specification .
- manifest.ttl MAY contain triples of the form
<extensionuri> rdfs:seeAlso <datafile.ttl> .
meaning the host should treat the contents of datafile.ttl as part of the LV2 specification (as if the data was included in lv2.ttl itself) - Hosts SHOULD use all of this data as their LV2 specification (not just lv2.ttl)
- 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).
[edit] Plugin Extension Bundle
A bundle which contains the implementation of an LV2 extension for a (possibly separate) plugin
- manifest.ttl contains the triple
<pluginuri> rdfs:seeAlso <foo.ttl> .
where foo.ttl contains any information necessary to discover and use the extension implementation (as defined by the LV2 extension) - Hosts SHOULD include foo.ttl as part of the plugin's data, as if the contents of foo.ttl 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 guiext:guiBinary, so manifest.ttl 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 manifest.ttl, or
<somepluginuri> rdfs:seeAlso <someplugingui.ttl> .
if the data is in someplugingui.ttl in the top level of the bundle directory. That file would then contain the triple
<somepluginuri> guiext:guiBinary <guibinary.so> .
