document new dlopen feature and packaging

Cargo.toml

@@ -8,7 +8,7 @@ license = "MIT"
 name = "jack"
 readme = "README.md"
 repository = "https:/RustAudio/rust-jack"
-version = "0.9.0"
+version = "0.9.1"
 
 [dependencies]
 bitflags = "1"

README.md

@@ -6,45 +6,39 @@
 [![crates.io](https://img.shields.io/crates/v/jack.svg)](https://crates.io/crates/jack)
 [![docs.rs](https://docs.rs/jack/badge.svg)](https://docs.rs/jack)
 
-Rust bindings for [JACK Audio Connection Kit](https://jackaudio.org).
+Rust bindings for the [JACK Audio Connection Kit](https://jackaudio.org). These bindings work on every
+operating system that JACK does.
 
-[:heart: Sponsor](https:/sponsors/wmedrano)
-
-Check out the `examples` directory for usage.
-
-## Crates
-
-```toml
-[dependencies]
-jack = "0.9"
-```
+The JACK server is usually started by the user or system. Clients can request that the JACK server is
+started on demand when they connect, but this can be disabled by the user and is the recommended
+configuration.
 
-### Windows
+ * Linux and BSD users may install JACK1, JACK2, or Pipewire JACK from their system package
+manager.
+ * Windows users may install JACK from the
+ [official website](http://jackaudio.org/downloads/) or
+ [Chocolatey](https://community.chocolatey.org/packages/jack).
+ * macOS users may install JACK from the [official website](http://jackaudio.org/downloads/) or
+ [Homebrew](https://formulae.brew.sh/formula/jack).
 
-Install `JACK` from the [official website](http://jackaudio.org/downloads/).
-libjack64.dll (or libjack.dll for 32bit) is required for Windows to work.
-
-## Running
-
-- `libjack` is required. Consult your package manager or the [official](http://jackaudio.org/downloads/) website.
-
-- The general workflow for a JACK application is to start up a JACK daemon and connect the client to it. [qjackctl](http://qjackctl.sourceforge.net/) is a convenient way to configure and bring up a JACK server through a GUI.
+[:heart: Sponsor](https:/sponsors/wmedrano)
 
-- [JACK FAQ](http://jackaudio.org/faq/)
+Refer to the [documentation](https://docs.rs/jack/) for details about the API, building, and packaging.
+Also take a look at the `examples` directory for usage.
 
 ## Testing
 
 Testing requires setting up a dummy server and running the tests using a single
 thread.
 
 ```bash
-# Set up a dummy server for tests.
+# Set up a dummy server for tests. The script is included in this repository.
 ./dummy_jack_server.sh &
 # Run tests with limited concurrency.
 RUST_TEST_THREADS=1 cargo test
 ```
 
-**Note:** We use a single thread for tests since too multiple client
+**Note:** We use a single thread for tests since too many client
 instantiations in short periods of time cause the JACK server to become flaky.
 
 ### Possible Issues

build.rs

@@ -0,0 +1,7 @@
+fn main() {
+ println!("cargo:rerun-if-env-changed=RUST_JACK_DLOPEN");
+ let dlopen = std::env::var("RUST_JACK_DLOPEN").is_ok();
+ if dlopen {
+ println!("cargo:rustc-cfg=feature=\"dlopen\"");
+ }
+}

jack-sys/Cargo.toml

@@ -6,7 +6,7 @@ license = "MIT OR Apache-2.0"
 links = "jack"
 name = "jack-sys"
 repository = "https:/RustAudio/rust-jack/tree/main/jack-sys"
-version = "0.3.3"
+version = "0.3.4"
 
 [dependencies]
 dlib = "0.5"

jack-sys/build.rs

@@ -1,8 +1,14 @@
 fn main() {
- // pkg-config is required to find PipeWire's implementation of libjack
- // Refer to https:/RustAudio/rust-jack/issues/142 for details.
- // Do not unwrap this because linking might still work if pkg-config is
- // not installed, for example on Windows.
- #[cfg(not(feature = "dlopen"))]
- let _ = pkg_config::probe_library("jack");
+ println!("cargo:rerun-if-env-changed=RUST_JACK_DLOPEN");
+ let dlopen = std::env::var("RUST_JACK_DLOPEN").is_ok();
+ if dlopen {
+ println!("cargo:rustc-cfg=feature=\"dlopen\"");
+ }
+ if !(dlopen || cfg!(feature = "dlopen")) {
+ // pkg-config is required to find PipeWire's implementation of libjack
+ // Refer to https:/RustAudio/rust-jack/issues/142 for details.
+ // Do not unwrap this because linking might still work if pkg-config is
+ // not installed, for example on Windows.
+ pkg_config::find_library("jack").unwrap();
+ }
 }

jack-sys/src/lib.rs

@@ -4,7 +4,7 @@ use dlib::external_library;
 use lazy_static::lazy_static;
 
 pub const JACK_LIB: &'static str =
- if cfg!(target_family = "windows") {
+ if cfg!(windows) {
  if cfg!(target_arch = "x86") {
  "libjack.dll"
  } else {

src/lib.rs

@@ -1,4 +1,40 @@
-//! Rust bindings for JACK, a real-time audio and midi library.
+//! Rust bindings for JACK, a real-time audio and midi library. These bindings are compatible with
+//! all implementations of JACK (Pipewire JACK, JACK1, and JACK2).
+//!
+//! # Linking, dynamic loading, and packaging
+//!
+//! libjack is shared among all clients on the system, so there must only be a single
+//! system-wide version of it. Applications typically should not ship their own copy of libjack.
+//! This is an issue for distributing JACK compatible applications on Windows and macOS. On Linux
+//! and BSDs, this is not an issue for system packages because the application and JACK server are
+//! both distributed by the system package manager.
+//!
+//! To handle this, use the `dlopen` Cargo feature, which is enabled by default. This feature
+//! dynamically loads libjack at runtime rather than linking libjack at build time. If the
+//! user does not have JACK installed at runtime, [Client::new] will return [Error::LoadLibraryError].
+//! In this case, have your application show an error message directing the user to install JACK from
+//! <https://jackaudio.org/downloads/> and, if available, fall back to another audio API.
+//!
+//! With the `dlopen` feature, neither libjack nor the JACK pkgconfig file need to be present at build
+//! time. This is convenient for automated Windows and macOS builds as well as cross compiling.
+//!
+//! If your application cannot be used without JACK, Linux and BSD packagers may prefer
+//! to link libjack at build time. To do this, disable the `dlopen` feature by using
+//! `default-features = false` in your application's Cargo.toml. For example:
+//!
+//! ```toml
+//! [target.'cfg(any(windows, target_vendor = "apple"))'.dependencies]
+//! # Load libjack at runtime.
+//! jack = "0.9"
+//!
+//! [target.'cfg(not(any(windows, target_vendor = "apple")))'.dependencies]
+//! # Link libjack at build time.
+//! jack = { version = "0.9", default-features = false }
+//! ```
+//!
+//! You can set the environment variable `RUST_JACK_DLOPEN` to `on` to enable the `dlopen` feature
+//! without needing to edit your application's Cargo.toml. This can be useful for cross compiling
+//! to Linux with a different CPU architecture.
 //!
 //! # Server
 //!