aboutsummaryrefslogtreecommitdiffstats
path: root/README
diff options
context:
space:
mode:
authorDavid Robillard <d@drobilla.net>2012-03-23 02:58:52 +0000
committerDavid Robillard <d@drobilla.net>2012-03-23 02:58:52 +0000
commit007786c0c3d3f1c0cfd78aac9a26e7f550f7db3b (patch)
tree7d7598a6eef566313f04e5046a643a02ddc5685c /README
parent382358caa9b8ea0b41b28e934574a7f0c5d5ff31 (diff)
downloadlv2-007786c0c3d3f1c0cfd78aac9a26e7f550f7db3b.tar.xz
Update README, remove INSTALL.
Diffstat (limited to 'README')
-rw-r--r--README89
1 files changed, 67 insertions, 22 deletions
diff --git a/README b/README
index 5e8ad52..2687acc 100644
--- a/README
+++ b/README
@@ -1,37 +1,82 @@
-This is a repository of all the extensions, scripts, and other useful LV2
-related tools at <http://lv2plug.in/>. Contributions are welcome, please
-send patches to the LV2 mailing list (see admin page at
-<http://lists.lv2plug.in/> to subscribe or browse archives).
+LV2
+===
-Note that many components of this repository are experimental, and NOT
-suitable for release or packaging. Release tarballs suitable for
-distribution can be found in build/default/spec after running gendoc.py.
+LV2 is a plugin standard for audio systems. It defines a minimal yet extensible
+C API for plugin code and a format for plugin "bundles". See
+<http://lv2plug.in> for more information.
-The build system and documentation generation requires only Python
-and Doxygen.
+This package contains specifications (a C header and/or a schema in Turtle),
+documentation generation tools, and example plugins.
+Building and installation requires only Python 2.6 and, optionally, Doxygen.
-** Installing Core/Extension Bundles **
-./waf configure
-./waf
-sudo ./waf install
+Installation
+------------
-The installation directory can be modified with the --lv2-dir or
---lv2-user options to ./waf configure, e.g.:
+A typical build looks something like this:
-./waf configure --lv2-dir /path/to/dir/to/place/bundles/under
+ ./waf configure --prefix /foo
+ ./waf
+ sudo ./waf install
-or
+or, for packaging:
-./waf configure --lv2-user
+ DESTDIR=/foo/lv2 ./waf install
-which will install to the default user LV2 directory (e.g. ~/.lv2).
+For help on the various options available, run:
+ ./waf --help
+The bundle installation directory can be set with the --lv2-dir option, e.g.:
-** Generating Core/Extension Documentation **
+ ./waf configure --lv2-dir /foo/lib/lv2
-./gendoc.py
+Similarly, --lv2-user will install to the user LV2 directory (e.g. ~/.lv2).
-Documentation output will be in build/default/doc.
+
+Packaging
+---------
+
+Specification bundles are both a build and run time dependency of programs that
+use LV2. Programs expect their data to be available somewhere in LV2_PATH.
+
+See <http://lv2plug.in/trac/wiki/Filesystem_Hierarchy_Standard> for details on
+the standard installation paths.
+
+Do not split up LV2 bundles, they must remain self-contained. This is a
+requirement, not a suggestion, and it supercedes any rules your distribution
+may have which were likely designed for libraries (note LV2 specifications are
+just text, not libraries). You are free to link or copy things anywhere, but
+under no circumstances should an incomplete part of a bundle be installed.
+
+Other than that, things may be split up in any way. In particular it is a good
+idea to split specifications, tools, and plugins into separate packages.
+
+
+Header Installation
+-------------------
+
+The install stage installs symbolic links to headers in bundles. This is to
+support universal C includes that do not change from system to system. For
+example, the URID extension's header can always be included like so:
+
+ #include "lv2/lv2plug.in/ns/ext/urid/urid.h"
+
+Note that some specification headers themselves have such include lines, which
+must not be modified. The details of how this is achieved are unimportant and
+may be tailored to particular systems. The requirement is simply that this
+style of include must work for any header in a specification.
+
+If you are having problems with symbolic links for whatever reason, configure
+with the --copy-headers option, which will make copies instead.
+
+
+Documentation
+-------------
+
+Configuring with the --docs option will build the documentation for all the
+included specifications if Doxygen is available. For example:
+
+ ./waf configure --docs
+ ./waf