From ed73356e710d9b20fce8bf98a15c9a63e54bd9d9 Mon Sep 17 00:00:00 2001 From: David Robillard Date: Fri, 21 Nov 2014 22:47:56 -0500 Subject: Organize site explicitly using pages. --- content/pages/bundle-definition.md | 104 +++++++++++++++++++++++++ content/pages/developer-information.md | 77 ------------------ content/pages/developing.md | 77 ++++++++++++++++++ content/pages/filesystem-hierarchy-standard.md | 38 +++++++++ content/pages/validating-lv2-data.md | 36 +++++++++ 5 files changed, 255 insertions(+), 77 deletions(-) create mode 100644 content/pages/bundle-definition.md delete mode 100644 content/pages/developer-information.md create mode 100644 content/pages/developing.md create mode 100644 content/pages/filesystem-hierarchy-standard.md create mode 100644 content/pages/validating-lv2-data.md (limited to 'content/pages') 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 ` a lv2:Plugin`. + +* The data files for each plugin are listed with the `rdfs:seeAlso` property, + for example ` rdfs:seeAlso `. + +* Descriptions may be split across several files, and several bundles. File + boundaries are not significant. + +* If a statement like ` a lv2:Specification` is found, then + `` 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 ` a pset:Preset` is found, then + `` 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 ` a lv2:Plugin`. + +* `manifest.ttl` MAY contain triples of the form ` rdfs:seeAlso + ` which indicates that more information can be found in + `datafile.ttl`. + +### Specification + +* `manifest.ttl` contains the triple ` a lv2:Specification`. + +* `manifest.ttl` MAY contain triples of the form ` rdfs:seeAlso + ` 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 ` 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 ` rdfs:seeAlso + ` which indicates that more information can be found in + `datafile.ttl`. + +* `manifest.ttl` contains a triple of the form ` ui:binary ` where + `ui.so` is the module to be dynamically loaded by the host. diff --git a/content/pages/developer-information.md b/content/pages/developer-information.md deleted file mode 100644 index dde7b49..0000000 --- a/content/pages/developer-information.md +++ /dev/null @@ -1,77 +0,0 @@ -Title: Developer Information - -The way to learn about implementing LV2 is by example. The documentation and -example projects listed below have been created specifically for this purpose, -look at these first. Copying an example as a template is recommended. - - -## What *not* to do - -If you are interested in implementing LV2, do *not* look at the specifications -and API references first! They are just that: references, and do not provide a -high-level view of how to get the job done. Once you have a basic working -implementation based on the examples, if you need more specific detail, then -the references are useful. - - -## Implementing Plugins - -LV2 includes several example plugins which are simple demonstrations of various -types of plugins and the features they require with thorough documentation. If -you prefer to read source code, they are in the `plugins` directory of the LV2 -distribution. - -If you would prefer to read a document, there is also a "book" generated from -the literate source code of these plugins: - -* [Programming LV2 Plugins](http://lv2plug.in/book) - - -## Implementing Hosts - -LV2 hosts use a library to handle all the details of plugin discovery, -investigation, and instantiation. [Lilv](http://drobilla.net/software/lilv) is -the standard library for this. - -* [Lilv API Reference](http://drobilla.net/docs/lilv/) - -Plans are currently underway to incorporate simple and thoroughly documented hosts into LV2, along the lines of the plugin -examples. Until then, several external projects serve as useful examples: - -* [lv2file](https://github.com/jeremysalwen/lv2file) is a very simple - single-file program that applies an LV2 plugin to an audio file. - -* [Jalv](http://drobilla.net/software/jalv) is a relatively simple yet - fully-featured [Jack](http://jackaudio.org) host for LV2 plugins. Start at - the core, [jalv.c](http://dev.drobilla.net/browser/trunk/jalv/src/jalv.c), - which weighs in at just under 1000 SLOC. Jalv also supports MIDI, embedded - GUIs, presets, state saving, and other features. - - -## Reference - -Most LV2 specifications have two parts: code and data. The "specification" -documentation comes from the data, and documents the various concepts in the -specification, with links to the API reference of the associated APIs. After -examples, this is the best place to better understand an extension. - -The API reference is generated from Doxygen, and serves the usual purpose. Go -there for documentation about a specific function, struct, or define. - -* [Specifications](http://lv2plug.in/ns) - -* [API Reference](http://lv2plug.in/doc/html) - - -## Help - -If you have any trouble or questions in general, ask on the -[mailing list](http://lists.lv2plug.in/listinfo.cgi/devel-lv2plug.in), or visit -us in [#lv2](http://webchat.freenode.net/?channels=lv2) on irc.freenode.net - - -## Other Resources - -* [Logo](http://lv2plug.in/logo) - -* [LV2 Achievement of GMPI Requirements](http://lv2plug.in/gmpi.html) diff --git a/content/pages/developing.md b/content/pages/developing.md new file mode 100644 index 0000000..dde7b49 --- /dev/null +++ b/content/pages/developing.md @@ -0,0 +1,77 @@ +Title: Developer Information + +The way to learn about implementing LV2 is by example. The documentation and +example projects listed below have been created specifically for this purpose, +look at these first. Copying an example as a template is recommended. + + +## What *not* to do + +If you are interested in implementing LV2, do *not* look at the specifications +and API references first! They are just that: references, and do not provide a +high-level view of how to get the job done. Once you have a basic working +implementation based on the examples, if you need more specific detail, then +the references are useful. + + +## Implementing Plugins + +LV2 includes several example plugins which are simple demonstrations of various +types of plugins and the features they require with thorough documentation. If +you prefer to read source code, they are in the `plugins` directory of the LV2 +distribution. + +If you would prefer to read a document, there is also a "book" generated from +the literate source code of these plugins: + +* [Programming LV2 Plugins](http://lv2plug.in/book) + + +## Implementing Hosts + +LV2 hosts use a library to handle all the details of plugin discovery, +investigation, and instantiation. [Lilv](http://drobilla.net/software/lilv) is +the standard library for this. + +* [Lilv API Reference](http://drobilla.net/docs/lilv/) + +Plans are currently underway to incorporate simple and thoroughly documented hosts into LV2, along the lines of the plugin +examples. Until then, several external projects serve as useful examples: + +* [lv2file](https://github.com/jeremysalwen/lv2file) is a very simple + single-file program that applies an LV2 plugin to an audio file. + +* [Jalv](http://drobilla.net/software/jalv) is a relatively simple yet + fully-featured [Jack](http://jackaudio.org) host for LV2 plugins. Start at + the core, [jalv.c](http://dev.drobilla.net/browser/trunk/jalv/src/jalv.c), + which weighs in at just under 1000 SLOC. Jalv also supports MIDI, embedded + GUIs, presets, state saving, and other features. + + +## Reference + +Most LV2 specifications have two parts: code and data. The "specification" +documentation comes from the data, and documents the various concepts in the +specification, with links to the API reference of the associated APIs. After +examples, this is the best place to better understand an extension. + +The API reference is generated from Doxygen, and serves the usual purpose. Go +there for documentation about a specific function, struct, or define. + +* [Specifications](http://lv2plug.in/ns) + +* [API Reference](http://lv2plug.in/doc/html) + + +## Help + +If you have any trouble or questions in general, ask on the +[mailing list](http://lists.lv2plug.in/listinfo.cgi/devel-lv2plug.in), or visit +us in [#lv2](http://webchat.freenode.net/?channels=lv2) on irc.freenode.net + + +## Other Resources + +* [Logo](http://lv2plug.in/logo) + +* [LV2 Achievement of GMPI Requirements](http://lv2plug.in/gmpi.html) 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. -- cgit v1.2.1