document new dlopen feature and packaging

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://github.com/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 convinient way to configure and bring up a JACK server through a GUI.
+[:heart: Sponsor](https://github.com/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

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,36 @@
-//! 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, 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 }
+//! ```
 //!
 //! # Server
 //!