build(ffmpeg): static GPL FFmpeg 8.0 via project script + FFMPEG_DIR

- tooling/ffmpeg/build-ffmpeg.sh builds release/8.0 static+PIC into
  .cache/ffmpeg: GPL/version3, every free-license external codec lib
  probed via pkg-config (enabled when present), per-OS hardware
  acceleration (VideoToolbox/AudioToolbox, VAAPI/VDPAU/libdrm,
  D3D11VA/DXVA2/MediaFoundation, nvenc when ffnvcodec exists)
- tooling/install-deps.sh installs those libraries on Homebrew / MSYS2
  UCRT64 / Debian-Ubuntu / Fedora / Arch; nothing in the build sudo's
- ffmpeg-next's own build feature is unusable (every crate-version to
  FFmpeg-release pairing is broken upstream: 9.0.0->FF9 AVCodec fields,
  8.1.0->FF8.1 new enum variants, 8.0.0->FF8 FF_PROFILE rename), so
  ffmpeg-next 9 + FFmpeg 8.x headers via FFMPEG_DIR it is
- new links-crate oakffmpeg-link emits the static FFmpeg's transitive
  link flags from its .pc files (cargo only propagates them from links
  crates, and rustc prunes the flags unless the rlib is referenced —
  hence the force_link statics)
- docs/build.md updated for the Rust workspace flow

crates/oakcodec/Cargo.toml

@@ -15,7 +15,20 @@ crate-type = ["staticlib", "rlib"]
 test-stubs = []
 
 [dependencies]
+oakffmpeg-link = { path = "../oakffmpeg-link" }
 oakcore-rs = { path = "../oakcore" }
 # Real media decode/encode. The C++ ffmpeg_bridge library existed only to
 # absorb FFmpeg API churn; the Rust crate calls ffmpeg-next directly.
-ffmpeg-next = "9"
+#
+# ffmpeg-next 9.x pairs with FFmpeg 8.x headers, which most distros do
+# not ship yet — build a matching GPL FFmpeg (all free-license codecs +
+# per-OS hardware acceleration, static+PIC) with
+# tooling/ffmpeg/build-ffmpeg.sh and point cargo at it via FFMPEG_DIR
+# (see docs/build.md). The `static` feature makes the linker prefer the
+# archives.
+#
+# ffmpeg-next's own `build` feature is NOT usable: it clones
+# release/<crate-version>, and every such pairing is broken upstream
+# (9.0.0 -> FFmpeg 9.0 removed AVCodec fields; 8.1.0 -> FFmpeg 8.1 added
+# enum variants; 8.0.0 -> FFmpeg 8.0 renamed FF_PROFILE_*).
+ffmpeg-next = { version = "9.0", features = ["static"] }

crates/oakcodec/src/lib.rs

@@ -52,3 +52,9 @@ pub mod timecodemetadata;
 
 #[cfg(test)]
 mod realmedia_tests;
+
+// Keep the oakffmpeg-link rlib referenced so its build script's native
+// link flags (the static FFmpeg's transitive dependencies) reach the
+// final link — rustc prunes the flags of an unreferenced rlib.
+#[used]
+static FORCE_FFMPEG_LINK: fn() = oakffmpeg_link::force_link;