README.md
1Weak-JACK
2=========
3
4This small library abstracts the [JACK](http://jackaudio.org) Application Binary Interface.
5
6Background and Motivation
7-------------------------
8
9The jack shared library needs to be installed system-wide (for all jack applications
10to share), it can not be part of an application itself.
11
12JACK developers take great care to not break binary compatibility of libjack. An
13application compiled with one version of jack will work with all future versions
14of jack. However, this only works well on GNU/Linux, BSD and to some extend on OSX.
15
16weak-jack linking is useful (at least) in the following cases:
17
18* the resulting application should not be directly linked to libjack.[so|dll|dylib]
19 IOW: the application should start even if libjack is not installed.
20* the ABI of libjack is not stable. Note, this is only relevant for the Windows .dll
21 (e.g. applications compiled and linked with jack-1.9.9 will crash with jack-1.9.10
22 on windows. -- MSVC has a workaround: link by function-name, not ordinal, mingw
23 does not offer this)
24* Reference new API functions (e.g. meta-data API or new latency compensation)
25 in the application, which is not available on older versions of jack.
26
27Usage
28-----
29
301. Copy the source files into your application's source (or use a git submodule)
312. replace all `#include<jack/*>` in your sources with `#include "weak-jack.h"`
323. add `weak_libjack.c` to the build-source of your project
33 (in case your build-system does not detect `#include` dependencies automatically,
34 also reference the header and .def file).
354. Define `USE_WEAK_JACK` for all platforms where you want to use weak-linking. Usually
36 `CFLAGS+=-DUSE_WEAK_JACK CXXFLAGS+=-DUSE_WEAK_JACK`
375. Do not link your application to libjack (`-ljack`) when `USE_WEAK_JACK` is defined.
38
39Note the jack-headers still need to be present when compiling the application.
40
41The application code itself does not need to be changed.
42
43The first call to `jack_client_open()` will try to find and load libjack, if it cannot be
44found, it will fail (return `NULL` and set `jack_status_t` if provided to `JackFailure`.)
45
46It is possible to explicitly initialize and query availability of libjack using
47`have_libjack();` it returns 0 if libjack is available and can be used. (see the header
48file for non-zero error codes).
49
50Caveats
51-------
52
53If libjack is not available, all `jack_*` API calls are turned into no-operation functions.
54This is not a problem in general, as jack-applications will not use any part of the jack API if
55jack_client_open fails. The only exception here may be `jack_ringbuffer`. Note that the ringbuffer
56implementation is also part of libjack and will not be available.
57
58The dummy implementation for the ringbuffer API is safe (read, writes are ignored and return failure
59or zero-bytes length), but if your application depends on it to work, you're out of luck :)
60
61The function wrappers in `weak_libjack.def` were collected pragmatically it's quite possible that
62some JACK API calls have been missed. If you application fails to link (without -ljack), please report
63at https://github.com/x42/weakjack/issues
64
65License
66-------
67
68GNU General Public License version 2 (or later).
69
70Alternatives
71------------
72
73An alternative, more liberally licensed, implementation that abstracts and wraps jack completely
74(incl headers) can be found at
75https://github.com/falkTX/Carla/tree/master/source/jackbridge (C++ only),
76and a jack2 specific version at https://github.com/sletz/jack2/blob/master/common/JackWeakAPI.c
77
78A variant for python bindings is also provided by falkTX:
79https://github.com/falkTX/Cadence/blob/master/src/jacklib.py
80