Weak-JACK
=========

This small library abstracts the [JACK](http://jackaudio.org) Application Binary Interface.

Background and Motivation
-------------------------

The jack shared library needs to be installed system-wide (for all jack applications
to share), it can not be part of an application itself.

JACK developers take great care to not break binary compatibility of libjack. An
application compiled with one version of jack will work with all future versions
of jack. However, this only works well on GNU/Linux, BSD and to some extend on OSX.

weak-jack linking is useful (at least) in the following cases:

*   the resulting application should not be directly linked to libjack.[so|dll|dylib]
    IOW: the application should start even if libjack is not installed.
*   the ABI of libjack is not stable. Note, this is only relevant for the Windows .dll
    (e.g. applications compiled and linked with jack-1.9.9 will crash with jack-1.9.10
		 on windows. -- MSVC has a workaround: link by function-name, not ordinal, mingw
		 does not offer this)
*   Reference new API functions (e.g. meta-data API or new latency compensation)
    in the application, which is not available on older versions of jack.

Usage
-----

1. Copy the source files into your application's source (or use a git submodule)
2. replace all `#include<jack/*>` in your sources with `#include "weak-jack.h"`
3. add `weak_libjack.c` to the build-source of your project
   (in case your build-system does not detect `#include` dependencies automatically,
	 also reference the header and .def file).
4. Define `USE_WEAK_JACK` for all platforms where you want to use weak-linking. Usually
   `CFLAGS+=-DUSE_WEAK_JACK  CXXFLAGS+=-DUSE_WEAK_JACK`
5. Do not link your application to libjack (`-ljack`) when `USE_WEAK_JACK` is defined.

Note the jack-headers still need to be present when compiling the application.

The application code itself does not need to be changed.

The first call to `jack_client_open()` will try to find and load libjack, if it cannot be
found, it will fail (return `NULL` and set `jack_status_t` if provided to `JackFailure`.)

It is possible to explicitly initialize and query availability of libjack using
`have_libjack();` it returns 0 if libjack is available and can be used. (see the header
file for non-zero error codes).

Caveats
-------

If libjack is not available, all `jack_*` API calls are turned into no-operation functions.
This is not a problem in general, as jack-applications will not use any part of the jack API if
jack_client_open fails. The only exception here may be `jack_ringbuffer`. Note that the ringbuffer
implementation is also part of libjack and will not be available.

The dummy implementation for the ringbuffer API is safe (read, writes are ignored and return failure
or zero-bytes length), but if your application depends on it to work, you're out of luck :)

The function wrappers in `weak_libjack.def` were collected pragmatically it's quite possible that
some JACK API calls have been missed. If you application fails to link (without -ljack), please report
at https://github.com/x42/weakjack/issues

License
-------

GNU General Public License version 2 (or later).

Alternatives
------------

An alternative, more liberally licensed, implementation that abstracts and wraps jack completely
(incl headers) can be found at
https://github.com/falkTX/Carla/tree/master/source/jackbridge (C++ only),
and a jack2 specific version at https://github.com/sletz/jack2/blob/master/common/JackWeakAPI.c

A variant for python bindings is also provided by falkTX:
https://github.com/falkTX/Cadence/blob/master/src/jacklib.py