Link system libva on Linux (fix undefined va* symbols when linked into a binary)

0.0.1's "dlopen" only skipped the link step, but the bindings are static extern
calls with no runtime loader, so any executable that pulls this crate (e.g.
moq-video's test binary) failed to link with undefined vaCreateBuffer/vaPutImage/
... symbols. An rlib tolerated it; a binary does not.

Resolve the symbols by linking the system libva / libva-drm via pkg-config, gated
to Linux (the only platform with VA-API). Bindings are still generated from the
pinned vendored headers, so the binding ABI can't drift; VA-API's ABI is stable
so a newer system libva links fine. On non-Linux hosts the crate only builds as
an rlib (symbols left for the final binary), so it stays compilable for dev.

A vaapi-enabled binary now requires libva.so at runtime — acceptable since the
feature targets VA-API hardware, which has libva. Updated README/Cargo.toml to
drop the (never-implemented) dlopen claim.

Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>

Author: kixelated

Cargo.toml

@@ -1,6 +1,6 @@
 [package]
 name = "moq-vaapi"
-version = "0.0.1"
+version = "0.0.2"
 description = "(AI GENERATED) VA-API H.264 hardware encoder, derived from discord/cros-libva + discord/cros-codecs"
 authors = ["The ChromiumOS Authors", "Discord", "Luke Curley <kixelated@gmail.com>"]
 repository = "https://github.com/moq-dev/vaapi"
@@ -14,12 +14,12 @@ rust-version = "1.85"
 # Dev-only tooling; not needed to build the crate from the published tarball.
 exclude = ["flake.nix", "flake.lock", "justfile", "deny.toml", "rust-toolchain.toml", ".rustfmt.toml"]
 
-# The build is hermetic: bindgen reads the vendored libva headers checked into
-# `libva/` (refreshed by `just vendor`, pinned to a known VA-API version so a
-# system libva bump can't drift the bindings), and libva is dlopen'd at runtime
-# rather than linked (so a built binary links on a libva-less host and starts on
-# machines without libva). There is no system-libva build path, so there are no
-# features to toggle: the build needs only libclang (for bindgen) on any OS.
+# bindgen reads the vendored libva headers checked into `libva/` (refreshed by
+# `just vendor`, pinned to a known VA-API version so a system libva bump can't
+# drift the bindings); libva itself is linked on Linux via pkg-config (VA-API's
+# ABI is stable, so a newer system libva links fine against the pinned bindings).
+# The rlib build needs only libclang + the vendored headers, so it compiles on any
+# OS (e.g. macOS) for development; the libva link only happens on Linux.
 
 [dependencies]
 anyhow = "1"
@@ -29,4 +29,5 @@ log = { version = "0", features = ["release_max_level_debug"] }
 
 [build-dependencies]
 bindgen = "0.70.1"
+pkg-config = "0.3.31"
 regex = "1.11.1"

README.md

@@ -21,13 +21,16 @@ pulled in as a git dependency.
 
 - **H.264 encode** over VA-API: tightly-packed NV12 in, an Annex-B elementary
   stream out (packed SPS/PPS + slice headers, low-latency IPPP, rate control).
-- **Hermetic build.** libva's headers are vendored into [`libva/`](./libva) (see
-  `just vendor`) and fed to bindgen, so the build needs **no system libva-dev** —
-  only `libclang`. The header version is pinned, so a system libva bump can't
-  drift the generated bindings.
-- **Runtime `dlopen`.** libva is loaded at runtime rather than linked, so a built
-  binary links on a libva-less builder and starts on machines without libva
-  (callers fall back to a software encoder).
+- **Pinned, vendored headers.** libva's headers are vendored into
+  [`libva/`](./libva) (see `just vendor`) and fed to bindgen, so generating the
+  bindings needs **no system libva-dev** — only `libclang` — and the pinned
+  version means a system libva bump can't drift the bindings.
+- **Links system libva on Linux.** The generated `va*` symbols are resolved by
+  linking the system `libva` / `libva-drm` (via pkg-config), so a `vaapi`-enabled
+  binary requires `libva.so` present at runtime — fine for a build that targets
+  VA-API hardware. VA-API's ABI is stable, so a newer system libva links against
+  the pinned bindings. (On non-Linux hosts the crate only builds as an rlib, which
+  leaves the symbols for the final binary, so it stays compilable for development.)
 
 ## Layout
 
@@ -47,8 +50,8 @@ nix develop --command just ci        # check + cargo-deny
 nix develop --command just vendor    # refresh libva/ headers from upstream
 ```
 
-The crate compiles on any OS (macOS included) because the build is header-only +
-dlopen; runtime use is Linux-only.
+The crate compiles on any OS (macOS included) — the rlib build is header-only and
+defers the libva link to the final binary, which is Linux-only.
 
 ## Licensing
 

build.rs

@@ -66,10 +66,10 @@ fn main() {
 	// libclang and the vendored headers, both available on docs.rs — so always generate.
 	let out_dir = PathBuf::from(env::var("OUT_DIR").expect("`OUT_DIR` is not set"));
 
-	// Always build against the vendored libva headers (checked into `libva/`,
-	// pinned to a known VA-API version) and dlopen libva at runtime rather than
-	// link it. There is no system-libva path, so the build needs only libclang for
-	// bindgen and works on any OS.
+	// Bindings are generated from the vendored libva headers (checked into `libva/`,
+	// pinned to a known VA-API version so a system libva bump can't drift them).
+	// libva itself is linked on Linux (see below). The rlib compile needs only
+	// libclang + the vendored headers, so it builds on any OS for development.
 	let (major, minor) = generate_vendored_version_header(&out_dir);
 	println!("cargo:rerun-if-changed=libva/meson.build");
 	println!("cargo:rerun-if-changed=libva/va/va_version.h.in");
@@ -122,6 +122,21 @@ fn main() {
 		println!("cargo::rustc-cfg=libva_1_10_or_higher");
 	}
 
+	// Bindings are generated from the vendored headers (pinned, drift-proof), but
+	// the va* symbols still have to resolve, so link the system libva on Linux (the
+	// only platform with VA-API). VA-API's ABI is stable, so a system libva newer
+	// than the vendored headers links fine. On other hosts (e.g. macOS) this crate
+	// only ever builds as an rlib, which leaves the symbols for the final binary, so
+	// skip linking and keep it compilable for development.
+	if env::var("CARGO_CFG_TARGET_OS").as_deref() == Ok("linux") {
+		pkg_config::Config::new()
+			.probe("libva")
+			.expect("libva not found via pkg-config (install libva / libva-dev)");
+		pkg_config::Config::new()
+			.probe("libva-drm")
+			.expect("libva-drm not found via pkg-config (install libva / libva-dev)");
+	}
+
 	let bindings = vaapi_gen_builder(bindgen::builder())
 		.header(WRAPPER_PATH)
 		.clang_arg(format!("-I{}", va_h_path.display()))