diff options
Diffstat (limited to 'content/pages')
| -rw-r--r-- | content/pages/bundle-definition.md | 104 | ||||
| -rw-r--r-- | content/pages/developing.md (renamed from content/pages/developer-information.md) | 0 | ||||
| -rw-r--r-- | content/pages/filesystem-hierarchy-standard.md | 38 | ||||
| -rw-r--r-- | content/pages/validating-lv2-data.md | 36 |
4 files changed, 178 insertions, 0 deletions
diff --git a/content/pages/bundle-definition.md b/content/pages/bundle-definition.md new file mode 100644 index 0000000..e82e3d8 --- /dev/null +++ b/content/pages/bundle-definition.md @@ -0,0 +1,104 @@ +Title: Bundle Definition +Date: 2014-11-20 20:16 +Category: Documentation + +An _LV2 Bundle_ is a directory containing the file `manifest.ttl` at the top +level, which is written in [Turtle](http://www.dajobe.org/2004/01/turtle/). +See the [Simple Amplifier manifest](http://lv2plug.in/book/#_manifest_ttl_in) +for an example. + +Note that host developers should use a library, such as +[Lilv](http://drobilla.net/software/lilv) which automatically discovers and +loads bundles correctly. This page describes the format of an LV2 bundle, but +host authors typically do not need to be concerned with the details. + +* All information necessary for a host to discover (but not necessarily use) + the contents of a bundle MUST be present in `manifest.ttl`. + +* The host can discover which plugins are present by scanning `manifest.ttl` + for statements like `<plugin-uri> a lv2:Plugin`. + +* The data files for each plugin are listed with the `rdfs:seeAlso` property, + for example `<plugin-uri> rdfs:seeAlso <datafile.ttl>`. + +* Descriptions may be split across several files, and several bundles. File + boundaries are not significant. + +* If a statement like `<extension-uri> a lv2:Specification` is found, then + `<extension-uri>` is specification which may contain information like + additional plugin categories, properties, and human-readable labels for + things. The host SHOULD load the corresponding data files. + +* If a statement like `<preset-uri> a pset:Preset` is found, then + `<preset-uri>` is a preset. The `lv2:appliesTo` property indices which + plugin the preset applies to. See the [presets + extension](http://lv2plug.in/ns/ext/presets) for details. + + + +## Installation + +* The name of a bundle itself MUST NOT be given any long-term significance (for + example, in saved files). + + * Hosts may include special plugin bundles as part of their installation + and depend on the existence of those bundles in their search path, but + otherwise the discovery process should be identical. + + * Users MUST be able to rename installed bundle directories without any + save files breaking. + + +## Discovery + +* If a host encounters a bundle it does not "understand" or care about, it may + simply ignore it. + +* Hosts MUST consider *all* data files associated with a plugin/spec/preset/etc + (including `manifest.ttl`) whenever looking for information about a plugin. + + +## Examples + +Note that `manifest.ttl` may contain information about any number of things. A +single bundle may contain several plugins, specifications, and presets. + +However, it is discouraged to group too many things into a single bundle, since +this makes it difficult for the user to manage what they have installed. +Instead, put individual plugins, presets, etc., in their own bundle. It is a +good idea to give related bundles common name prefix (not suffix) to make their +organization clear. + +### Plugin + +* `manifest.ttl` contains the triple `<pluginuri> a lv2:Plugin`. + +* `manifest.ttl` MAY contain triples of the form `<pluginuri> rdfs:seeAlso + <datafile.ttl>` which indicates that more information can be found in + `datafile.ttl`. + +### Specification + +* `manifest.ttl` contains the triple `<specuri> a lv2:Specification`. + +* `manifest.ttl` MAY contain triples of the form `<specuri> rdfs:seeAlso + <datafile.ttl>` which indicates that more information can be found in + `datafile.ttl`. + +* Hosts SHOULD consider this information part of their LV2 specification. + Hosts SHOULD NOT hard-code static assumptions about the specification, such + as plugin categories or port types (though of course, they may not support + unknown types). + +### UI + +* `manifest.ttl` contains the triple `<ui> a foo:MegaWidget` where + `foo:MegaWidget` is a "widget" type the host understands (likely one defined + in the [UI specification](http://lv2plug.in/ns/extensions/ui)). + +* `manifest.ttl` MAY contain triples of the form `<ui> rdfs:seeAlso + <datafile.ttl>` which indicates that more information can be found in + `datafile.ttl`. + +* `manifest.ttl` contains a triple of the form `<ui> ui:binary <ui.so>` where + `ui.so` is the module to be dynamically loaded by the host. diff --git a/content/pages/developer-information.md b/content/pages/developing.md index dde7b49..dde7b49 100644 --- a/content/pages/developer-information.md +++ b/content/pages/developing.md diff --git a/content/pages/filesystem-hierarchy-standard.md b/content/pages/filesystem-hierarchy-standard.md new file mode 100644 index 0000000..4f06a9f --- /dev/null +++ b/content/pages/filesystem-hierarchy-standard.md @@ -0,0 +1,38 @@ +Title: Filesystem Hierarchy Standard +Date: 2014-11-20 20:16 +Category: Documentation + +This page defines the standard locations where LV2 data should be installed. +All LV2 data is installed in [bundles](bundle-definition.html) which are discovered by hosts and other tools. + +LV2 bundles are self-contained and may contain any kind of data (binary, text, executable, system-specific, portable, etc.). These different kinds of data are not installed to separate paths as in the traditional Unix FHS. There is one important distinction, however: user-specific and system-wide bundles. User-specific bundles are likely writable by the user, while system-wide bundles appear to all users and are read-only. + +## Standard Paths + +LV2 bundles (directories typically named like "foo.lv2") SHOULD be in these standard locations: + +Platform | User Specific | System Wide +---------|------------------------------------|------------------------------ +Unix | `$HOME/.lv2` | `$PREFIX/lib/lv2` +Mac OS X | `$HOME/Library/Audio/Plug-Ins/LV2` | `/Library/Audio/Plug-Ins/LV2` +Windows | `%APPDATA%/LV2` | `%COMMONPROGRAMFILES%/LV2` + +$PREFIX should be /usr/local by default in all source distributions. + +## Bundle Discovery - LV2_PATH + +The environment variable `LV2_PATH` is the search path for LV2 bundles. Like the PATH variable for programs, it is colon-delimited on Unix and OSX, semicolon-delimited on Windows, and searched from left to right. Based on the above locations, the default `LV2_PATH` is: + +Platform | Default Path +---------|------------- +Unix | `$HOME/.lv2:/usr/local/lib/lv2:/usr/lib/lv2` +Mac OS X | `$HOME/Library/Audio/Plug-Ins/LV2:/Library/Audio/Plug-Ins/LV2:/usr/local/lib/lv2:/usr/lib/lv2` +Windows | `%APPDATA%/LV2;%COMMONPROGRAMFILES%/LV2` + +## User Saved Data (e.g. Presets) + +Hosts may wish to write data to bundles at run time (e.g. to save a preset, metadata, or even new plugins). The user specific portion of LV2_PATH should be used for this so hosts will automatically discover this data. It is best to write separate bundles for such things so the user can easy manage them with the shell or file manager. Whenever writing to a bundle, a file lock should be held on the `manifest.ttl` file. + +## Bundle Names + +Bundle directory names are NOT strong identifiers, and may be different from system to system (or at different times on the same system). Users may change them freely for any reason without fear of breakage. Accordingly, hosts *MUST NOT_' attach significance to bundle names between invocations (e.g. in save files). LV2 plugins and other resources '_MUST* be referred to by URI in save files, NOT by file system path.
\ No newline at end of file diff --git a/content/pages/validating-lv2-data.md b/content/pages/validating-lv2-data.md new file mode 100644 index 0000000..2a48e89 --- /dev/null +++ b/content/pages/validating-lv2-data.md @@ -0,0 +1,36 @@ +Title: Validating LV2 Data +Date: 2014-11-20 21:33 +Category: Documentation + +Because LV2 data written in Turtle does not need to be compiled like C, the +author must take care to ensure it is valid. For example, if there is a typo +in a predicate, a plugin may silently fail to work correctly. + +To prevent this kind of error, use `sord_validator` from +[Sord](http://drobilla.net/software/sord). This program will check that all +the properties in a set of Turtle data are actually defined, that the domain +and range is valid, and that typed literals are valid (for example, that they +have the correct type, or that `lv2:symbol` properties are actually valid LV2 +symbols). + +To do this, the validator needs to be passed all relevant data, including the +vocabularies which define the properties and classes used. The LV2 +distribution contains all the external vocabularies used in the `schemas` +directory. If `sord_validate` is installed, and an LV2 source tree is present, +then LV2 data can be checked like so: + + :::sh + sord_validate $(find /path/to/lv2-x.y.z -name '*.ttl') /path/to/data.ttl + +To check all data in your bundle: + + :::sh + sord_validate $(find /path/to/lv2-x.y.z -name '*.ttl') $(find /path/to/bundle.lv2 -name '*.ttl') + +For those unfamiliar with UNIX basics, the `find` command finds all files +matching a pattern, and putting a command in `$()` on a command line +substitutes the output of that command in place. So, these commands simply +expand to `sord_validate` being called with a list of files as arguments. + +Developers SHOULD include targets in their build scripts for running the +validator to ensure plugin data is correct before distribution. |