Including Extension Headers

Many extensions (and LV2Core itself) provide C headers with useful and/or required definitions for implementing the extension. This poses a problem: how should code <code>#include</code> these header files?

A standard, consistent form for including the header of a given LV2 extension is necessary. There are many reasons for this; the most obvious is that extension headers may need to include other extension headers (which obviously can not be done using a host-specific include style, e.g. one including the bundle path). Because extensions already have a universal identifier (their URI), include paths are based on this (the only alternative would be to create two identifiers for extensions, which would cause many problems).

Extensions includes always use quotes (not angle brackets) and begin with "lv2/" followed by the extension URI with scheme and authority omitted, e.g.: <pre> #include "lv2/lv2plug.in/ns/ext/event/event.h" </pre>

This applies to lv2.h itself as well. The standard way to include lv2.h is: <pre> #include "lv2/lv2plug.in/ns/lv2core/lv2.h" </pre>

Any header in an extension bundle may be included this way (e.g. for extensions that provide an optional "helper" header).

This include style is the universal way to include an extension header; it can work for all scenarios (e.g. system installed extensions, or extension shipped with a plugin/host) and since it is URI-based it is decentralised. There are many convenient benefits, e.g. copy copying is easy (no need to translate between build systems or source layouts) and finding documentation for an extension encountered in code is simple (just copy the path into a web browser's address bar without the leading "lv2/").

lv2config

Of course, for this to be possible, an appropriate directory structure must exist somewhere on the system. LV2Core (as of revision 4) includes a utility called <tt>lv2config</tt> which automatically generates this directory structure by creating symlinks to installed specification bundles. <tt>lv2config</tt> can be used to build a system-wide include tree (e.g. /usr/include/lv2/*) for system-installed extensions, or to build an include tree in a project (to allow shipping bundles with a project while still using standard style includes). <tt>lv2config</tt> must be run after an extension is installed to enable compiling against that extension.

Note the <code>lv2config</code> name is deliberately analogous to <code>ldconfig</code> since the concept is similar: to use an installed extension/library, you must first run lv2config/ldconfig. Distribution packages SHOULD do this automatically, so users/developers don't have to care or even know about this.