packaging.adoc: CRLF->LF
This commit is contained in:
parent
1c16fc8fa1
commit
1db5e34030
308
packaging.adoc
308
packaging.adoc
|
|
@ -1,154 +1,154 @@
|
|||
:docinfo: private-header
|
||||
:keywords: LADI, JACK, jack-audio-connection-kit, packaging, linux, downstream
|
||||
:toc:
|
||||
|
||||
== Packaging scenarios
|
||||
There are three scenarios (use cases) for JACK, related to D-Bus, from users point of view:
|
||||
|
||||
* Classic JACK only (UNSUPPORTED in LADI project)
|
||||
* D-Bus only JACK
|
||||
* D-Bus JACK and Classic JACK mixture (UNSUPPORTED in LADI project)
|
||||
|
||||
NOTE: All these scenarios don't affect interaction of normal JACK programs (ardour, hydrogen, etc) with JACK server.
|
||||
|
||||
Apart from D-Bus only functionality availability, they affect JACK server auto-launching and thus overall user experience. If more than one scenario is supposed to be available for user, typically package "flavors" are used.
|
||||
|
||||
=== Scenario 1: Classic JACK only
|
||||
|
||||
IMPORTANT: This scenario is not supported by LADI project and is kept for reference.
|
||||
|
||||
This is the traditional scenario, pre jackdbus for jack1 and the one enabled with "classic" configure option of jackaudio/jack2 waf build system.
|
||||
|
||||
Server auto-launching is implemented as fork+exec (starting new process) of jackd executable - the classic JACK server launcher.
|
||||
|
||||
* Pros:
|
||||
** This is the classic environment most current JACK users are aware of.
|
||||
* Cons:
|
||||
** User is blind about what happens with JACK server execution if it auto-started rather than manually started.
|
||||
** No JACK D-Bus only control/monitor applications can be used.
|
||||
** [line-through]#No audio card negotiation with PulseAudio.#
|
||||
|
||||
=== Scenario 2: D-Bus only JACK
|
||||
|
||||
Server auto-launching is implemented as D-Bus call that auto-activates JACK D-Bus service, in case it is not already started, and starts the JACK server. Correct interaction with PulseAudio is done using a D-Bus based audio card "acquire/release" mechanism. When JACK server starts, it asks this D-Bus service to acquire the audio card and PulseAudio will unconditionally release it. When JACK server stops, it releases the audio card that can be grabbed again by PulseAudio.
|
||||
|
||||
* Pros:
|
||||
** JACK D-Bus aware control/monitor applications can be used, resulting in much better [Linux] end-user (especially desktop) experience.
|
||||
** Audio card negotiation with PulseAudio.
|
||||
* Cons:
|
||||
** This is/was not the classic environment most current JACK users are/were aware of before year 2008.
|
||||
** If D-Bus session bus gets misconfigured/non-functional, user is not able to use JACK server before fixing it.
|
||||
|
||||
=== Scenario 3: D-Bus JACK and Classic JACK mixture
|
||||
|
||||
IMPORTANT: This scenario is not supported by LADI project and is kept for reference.
|
||||
|
||||
Both D-Bus launcher (jackdbus executable) and classic launcher (jackd executable) are installed. Server auto-launching is implemented as fork+exec (starting new process) of jackd executable - the classic JACK server launcher. [line-through]#Audio card negotiation with PulseAudio in implemented in jackdbus only.#
|
||||
|
||||
* Pros:
|
||||
** If D-Bus session bus gets misconfigured/non-functional, user is able to fallback to jackd, with its pros and cons.
|
||||
** User can start the JACK server both through jackdbus and jackd (and also through qjackctl when configured without jackdbus supoprt).
|
||||
** [line-through]#Audio card negotiation with PulseAudio if and only if jackdbus is used.#
|
||||
* Cons:
|
||||
** non-dbus aware tools (like qjackctl when configured without jackdbus support) or auto-launching will start jackd, associated with:
|
||||
*** User is blind about what happens with JACK server execution if jackd is autolaunched.
|
||||
*** No JACK D-Bus aware control/monitor applications can be used. They will claim JACK server is not started (cannot be contacted) even when JACK server is actually running and normal JACK applications are connected and probably using it.
|
||||
*** PulseAudio will not know whether JACK server is running
|
||||
* jackd and jackdbus will use different storage for JACK server configuration. jackd will be typically started through the `~/.jackdrc` *script* or `qjackctl`. jackdbus reads and stores settings in `~/.config/jack/conf.xml`
|
||||
|
||||
== How to package jack-audio-connection-kit components (LADI jackdbus and others)
|
||||
|
||||
* `jack server frontend` - virtual package provided by `jackd` and `jackdbus` packages
|
||||
* `jack server (library)` - package containing libjackserver.so at least. Maybe also: essential tools, drivers, inprocess clients.
|
||||
* `jackd` - package containing jackd binary. This package depends on `jack server (library)`
|
||||
* `jackdbus` - package containing jackdbus binary and jack_control script. This package depends on `jack server (library)`
|
||||
* `jack client library` - package containing libjack.so
|
||||
* `jack client library dev` - package containging headers and pkgconfig file for libjack.so
|
||||
* `jack server library dev` - package containging headers and pkgconfig file for libjackserver.so
|
||||
|
||||
`jack client library` and `jack server (library)` packages should be version coupled because they use internal IPC protocol that is not guaranteed to be compatible between versions.
|
||||
|
||||
All different releases of JACK should be considered internally incompatible - that is, it should never be considered possible to mix versions of the JACK server with other versions of the JACK library/ies, drivers or internal clients. Packaging should ensure that no packages associated with different releases of JACK are ever installed simultaneously. Especially, having two versions of libjack.so installed simultaneously, often causes JACK programs using one libjack version not being able to operate with JACK server of other version.
|
||||
|
||||
* An app that uses jack as only audio interfaces, (jack_keyboard for example), depends on `jack client library` package and on the `jack server frontend` virtual package
|
||||
* An app that uses jack as alternative (not the only) audio interface, (mplayer for exmaple), depends on `jack client library` and suggests `jack server frontend` virtual package
|
||||
* `ardour` depends on `jack client library` and depends on `jackd` package, because it can start jack server through jackd binary.
|
||||
* `qjackctl` if built without jackdbus support (unsupported scenario in LADI project) depends on `jack client library`. If built with `jackdbus`, it depends on `jack server frontend` package. qjackctl can start jack server through either `jackd` or `jackdbus` binary.
|
||||
* `laditools` depends on `jackdbus` only
|
||||
|
||||
== JACK server auto-start behaviour of libjack.so
|
||||
|
||||
While jack2 can be configured with auto-start of JACK server (through jackdbus) and this will cause creation of automatic studio in LADISH, autolaunching is better to not be used in jack modular scenarios with LADISH. Instead, initial auto-created studio can be achieved by starting jack server manually through `jack_control start`.
|
||||
|
||||
In case LADISH is not in effect, auto-starting behaviour of libjack depends on packager's choice. See also the Packaging scenarios section.
|
||||
|
||||
|
||||
== Installation layout on a Linux system.
|
||||
|
||||
=== Binaries
|
||||
|
||||
This includes:
|
||||
|
||||
* `jackdbus` - The D-Bus frontend for JACK server
|
||||
* `jack_control` - Commandline frontend to jackdbus
|
||||
|
||||
They are to be installed in `<PREFIX>/bin/`.
|
||||
|
||||
=== Libraries
|
||||
|
||||
This includes:
|
||||
|
||||
* `libjack` - library that JACK-aware client applications link to
|
||||
* `libjackserver` - library that JACK-aware server applications link to
|
||||
|
||||
The `libjack`, `libjacknet` and `libjackserver` libraries are to be installed in `<PREFIX>/lib64/` (for 64-bit libraries) or `<PREFIX>/lib/` (for 32-bit libraries).
|
||||
|
||||
SONAME of libjack is libjack.so.0, so symbolic link should be created, like this:
|
||||
|
||||
libjack.so.0 --> libjack.so.0.1.0
|
||||
libjack.so.0.1.0
|
||||
|
||||
Depending on JACK server version, the libjack.so.0 symlink target
|
||||
will be different. libjack.so.0.1.0 is the version from JACK2.
|
||||
|
||||
=== Drivers
|
||||
|
||||
Jack drivers are installed into `<PREFIX>/lib/jack/` as dynamic libraries.
|
||||
|
||||
=== In-process clients
|
||||
|
||||
In-process clients are installed into `<PREFIX>/lib/jack/`.
|
||||
|
||||
=== D-Bus service file
|
||||
|
||||
`jackdbus` service is auto-activated upon request through a D-Bus service file installed system-wide. The org.jackaudio.service file instructs the D-Bus session bus how to activate the JACK controller object upon request.
|
||||
|
||||
By default the `org.jackaudio.service` file is installed in `<PREFIX>/share/dbus-1/services/`.
|
||||
|
||||
NOTE: When not built as system-wide installed sesion bus dbus service, jackdbus can be configured with --enable-pkg-config-dbus-service-dir so to the system-wide D-Bus service directory. --enable-pkg-config-dbus-service-dir is unsupported in packged versions. If the service file is installed in a different prefix, the D-Bus session bus daemon configuration should be adjuste so to search in the appropriate directory.
|
||||
|
||||
=== Headers
|
||||
|
||||
C headers are installed in a JACK specific header directory, `<PREFIX>/include/jack/`.
|
||||
|
||||
=== pkg-config
|
||||
|
||||
`jack.pc` is to be installed installed in `<PREFIX>/lib64/pkgconfig/` (for 64-bit) or `<PREFIX>/lib/pkgconfig/` (for 32-bit).
|
||||
|
||||
=== User documentation
|
||||
|
||||
Man pages are installed in `<PREFIX>/share/man/man1/`.
|
||||
|
||||
=== Development documentation
|
||||
|
||||
HTML documentation is installed in a JACK specific directory `<PREFIX>/share/jack-audio-connection-kit`.
|
||||
|
||||
The index file of the HTML documentation is in `<PREFIX>/share/jack-audio-connection-kit/reference/html/`.
|
||||
|
||||
=== Filesystem relocation
|
||||
|
||||
Some unusual things related to installation relocateability:
|
||||
|
||||
* in-process clients and drivers are loaded from a fixed path (`<PREFIX>/lib/jack/`), specified literally during build. Drivers load directory may be overridden using the `JACK_DRIVER_DIR` environment variable. At the moment there is no way to override the in-process client directory.
|
||||
* The D-Bus session bus daemon configuration may need modification to be able to auto-activate the JACK controller service.
|
||||
* The `jack.pc` file contains `<PREFIX>`.
|
||||
:docinfo: private-header
|
||||
:keywords: LADI, JACK, jack-audio-connection-kit, packaging, linux, downstream
|
||||
:toc:
|
||||
|
||||
== Packaging scenarios
|
||||
There are three scenarios (use cases) for JACK, related to D-Bus, from users point of view:
|
||||
|
||||
* Classic JACK only (UNSUPPORTED in LADI project)
|
||||
* D-Bus only JACK
|
||||
* D-Bus JACK and Classic JACK mixture (UNSUPPORTED in LADI project)
|
||||
|
||||
NOTE: All these scenarios don't affect interaction of normal JACK programs (ardour, hydrogen, etc) with JACK server.
|
||||
|
||||
Apart from D-Bus only functionality availability, they affect JACK server auto-launching and thus overall user experience. If more than one scenario is supposed to be available for user, typically package "flavors" are used.
|
||||
|
||||
=== Scenario 1: Classic JACK only
|
||||
|
||||
IMPORTANT: This scenario is not supported by LADI project and is kept for reference.
|
||||
|
||||
This is the traditional scenario, pre jackdbus for jack1 and the one enabled with "classic" configure option of jackaudio/jack2 waf build system.
|
||||
|
||||
Server auto-launching is implemented as fork+exec (starting new process) of jackd executable - the classic JACK server launcher.
|
||||
|
||||
* Pros:
|
||||
** This is the classic environment most current JACK users are aware of.
|
||||
* Cons:
|
||||
** User is blind about what happens with JACK server execution if it auto-started rather than manually started.
|
||||
** No JACK D-Bus only control/monitor applications can be used.
|
||||
** [line-through]#No audio card negotiation with PulseAudio.#
|
||||
|
||||
=== Scenario 2: D-Bus only JACK
|
||||
|
||||
Server auto-launching is implemented as D-Bus call that auto-activates JACK D-Bus service, in case it is not already started, and starts the JACK server. Correct interaction with PulseAudio is done using a D-Bus based audio card "acquire/release" mechanism. When JACK server starts, it asks this D-Bus service to acquire the audio card and PulseAudio will unconditionally release it. When JACK server stops, it releases the audio card that can be grabbed again by PulseAudio.
|
||||
|
||||
* Pros:
|
||||
** JACK D-Bus aware control/monitor applications can be used, resulting in much better [Linux] end-user (especially desktop) experience.
|
||||
** Audio card negotiation with PulseAudio.
|
||||
* Cons:
|
||||
** This is/was not the classic environment most current JACK users are/were aware of before year 2008.
|
||||
** If D-Bus session bus gets misconfigured/non-functional, user is not able to use JACK server before fixing it.
|
||||
|
||||
=== Scenario 3: D-Bus JACK and Classic JACK mixture
|
||||
|
||||
IMPORTANT: This scenario is not supported by LADI project and is kept for reference.
|
||||
|
||||
Both D-Bus launcher (jackdbus executable) and classic launcher (jackd executable) are installed. Server auto-launching is implemented as fork+exec (starting new process) of jackd executable - the classic JACK server launcher. [line-through]#Audio card negotiation with PulseAudio in implemented in jackdbus only.#
|
||||
|
||||
* Pros:
|
||||
** If D-Bus session bus gets misconfigured/non-functional, user is able to fallback to jackd, with its pros and cons.
|
||||
** User can start the JACK server both through jackdbus and jackd (and also through qjackctl when configured without jackdbus supoprt).
|
||||
** [line-through]#Audio card negotiation with PulseAudio if and only if jackdbus is used.#
|
||||
* Cons:
|
||||
** non-dbus aware tools (like qjackctl when configured without jackdbus support) or auto-launching will start jackd, associated with:
|
||||
*** User is blind about what happens with JACK server execution if jackd is autolaunched.
|
||||
*** No JACK D-Bus aware control/monitor applications can be used. They will claim JACK server is not started (cannot be contacted) even when JACK server is actually running and normal JACK applications are connected and probably using it.
|
||||
*** PulseAudio will not know whether JACK server is running
|
||||
* jackd and jackdbus will use different storage for JACK server configuration. jackd will be typically started through the `~/.jackdrc` *script* or `qjackctl`. jackdbus reads and stores settings in `~/.config/jack/conf.xml`
|
||||
|
||||
== How to package jack-audio-connection-kit components (LADI jackdbus and others)
|
||||
|
||||
* `jack server frontend` - virtual package provided by `jackd` and `jackdbus` packages
|
||||
* `jack server (library)` - package containing libjackserver.so at least. Maybe also: essential tools, drivers, inprocess clients.
|
||||
* `jackd` - package containing jackd binary. This package depends on `jack server (library)`
|
||||
* `jackdbus` - package containing jackdbus binary and jack_control script. This package depends on `jack server (library)`
|
||||
* `jack client library` - package containing libjack.so
|
||||
* `jack client library dev` - package containging headers and pkgconfig file for libjack.so
|
||||
* `jack server library dev` - package containging headers and pkgconfig file for libjackserver.so
|
||||
|
||||
`jack client library` and `jack server (library)` packages should be version coupled because they use internal IPC protocol that is not guaranteed to be compatible between versions.
|
||||
|
||||
All different releases of JACK should be considered internally incompatible - that is, it should never be considered possible to mix versions of the JACK server with other versions of the JACK library/ies, drivers or internal clients. Packaging should ensure that no packages associated with different releases of JACK are ever installed simultaneously. Especially, having two versions of libjack.so installed simultaneously, often causes JACK programs using one libjack version not being able to operate with JACK server of other version.
|
||||
|
||||
* An app that uses jack as only audio interfaces, (jack_keyboard for example), depends on `jack client library` package and on the `jack server frontend` virtual package
|
||||
* An app that uses jack as alternative (not the only) audio interface, (mplayer for exmaple), depends on `jack client library` and suggests `jack server frontend` virtual package
|
||||
* `ardour` depends on `jack client library` and depends on `jackd` package, because it can start jack server through jackd binary.
|
||||
* `qjackctl` if built without jackdbus support (unsupported scenario in LADI project) depends on `jack client library`. If built with `jackdbus`, it depends on `jack server frontend` package. qjackctl can start jack server through either `jackd` or `jackdbus` binary.
|
||||
* `laditools` depends on `jackdbus` only
|
||||
|
||||
== JACK server auto-start behaviour of libjack.so
|
||||
|
||||
While jack2 can be configured with auto-start of JACK server (through jackdbus) and this will cause creation of automatic studio in LADISH, autolaunching is better to not be used in jack modular scenarios with LADISH. Instead, initial auto-created studio can be achieved by starting jack server manually through `jack_control start`.
|
||||
|
||||
In case LADISH is not in effect, auto-starting behaviour of libjack depends on packager's choice. See also the Packaging scenarios section.
|
||||
|
||||
|
||||
== Installation layout on a Linux system.
|
||||
|
||||
=== Binaries
|
||||
|
||||
This includes:
|
||||
|
||||
* `jackdbus` - The D-Bus frontend for JACK server
|
||||
* `jack_control` - Commandline frontend to jackdbus
|
||||
|
||||
They are to be installed in `<PREFIX>/bin/`.
|
||||
|
||||
=== Libraries
|
||||
|
||||
This includes:
|
||||
|
||||
* `libjack` - library that JACK-aware client applications link to
|
||||
* `libjackserver` - library that JACK-aware server applications link to
|
||||
|
||||
The `libjack`, `libjacknet` and `libjackserver` libraries are to be installed in `<PREFIX>/lib64/` (for 64-bit libraries) or `<PREFIX>/lib/` (for 32-bit libraries).
|
||||
|
||||
SONAME of libjack is libjack.so.0, so symbolic link should be created, like this:
|
||||
|
||||
libjack.so.0 --> libjack.so.0.1.0
|
||||
libjack.so.0.1.0
|
||||
|
||||
Depending on JACK server version, the libjack.so.0 symlink target
|
||||
will be different. libjack.so.0.1.0 is the version from JACK2.
|
||||
|
||||
=== Drivers
|
||||
|
||||
Jack drivers are installed into `<PREFIX>/lib/jack/` as dynamic libraries.
|
||||
|
||||
=== In-process clients
|
||||
|
||||
In-process clients are installed into `<PREFIX>/lib/jack/`.
|
||||
|
||||
=== D-Bus service file
|
||||
|
||||
`jackdbus` service is auto-activated upon request through a D-Bus service file installed system-wide. The org.jackaudio.service file instructs the D-Bus session bus how to activate the JACK controller object upon request.
|
||||
|
||||
By default the `org.jackaudio.service` file is installed in `<PREFIX>/share/dbus-1/services/`.
|
||||
|
||||
NOTE: When not built as system-wide installed sesion bus dbus service, jackdbus can be configured with --enable-pkg-config-dbus-service-dir so to the system-wide D-Bus service directory. --enable-pkg-config-dbus-service-dir is unsupported in packged versions. If the service file is installed in a different prefix, the D-Bus session bus daemon configuration should be adjuste so to search in the appropriate directory.
|
||||
|
||||
=== Headers
|
||||
|
||||
C headers are installed in a JACK specific header directory, `<PREFIX>/include/jack/`.
|
||||
|
||||
=== pkg-config
|
||||
|
||||
`jack.pc` is to be installed installed in `<PREFIX>/lib64/pkgconfig/` (for 64-bit) or `<PREFIX>/lib/pkgconfig/` (for 32-bit).
|
||||
|
||||
=== User documentation
|
||||
|
||||
Man pages are installed in `<PREFIX>/share/man/man1/`.
|
||||
|
||||
=== Development documentation
|
||||
|
||||
HTML documentation is installed in a JACK specific directory `<PREFIX>/share/jack-audio-connection-kit`.
|
||||
|
||||
The index file of the HTML documentation is in `<PREFIX>/share/jack-audio-connection-kit/reference/html/`.
|
||||
|
||||
=== Filesystem relocation
|
||||
|
||||
Some unusual things related to installation relocateability:
|
||||
|
||||
* in-process clients and drivers are loaded from a fixed path (`<PREFIX>/lib/jack/`), specified literally during build. Drivers load directory may be overridden using the `JACK_DRIVER_DIR` environment variable. At the moment there is no way to override the in-process client directory.
|
||||
* The D-Bus session bus daemon configuration may need modification to be able to auto-activate the JACK controller service.
|
||||
* The `jack.pc` file contains `<PREFIX>`.
|
||||
|
|
|
|||
Loading…
Reference in New Issue