rockbox_ffi_nif
Shared Erlang NIF over the librockbox_ffi C ABI —
the Rockbox DSP / metadata / codecs / playback engine exposed to the BEAM.
This is the common native layer for the language bindings that run on the
BEAM. The Elixir (rockbox_ex_ffi) and Gleam
(rockbox_ffi) packages both depend on this one instead of each vendoring
their own copy of the C shim and Erlang loader; the ergonomic wrappers live in
those packages.
What's here
| Path | Role |
|---|---|
c_src/rockbox_ffi_nif.c | erl_nif shim — a 1:1 surface of include/rockbox_ffi.h |
src/rockbox_ffi_nif.erl | NIF loader + stub module; downloads the .so on first load |
priv/rockbox_ffi_nif.manifest | per-triple sha256 checksums for the first-load download |
Makefile | local-dev build of priv/rockbox_ffi_nif.so |
NIF delivery
The compiled NIF is a multi-megabyte shared object (it statically links the
Rust librockbox_ffi.a), too large to bundle in a Hex tarball. So the Hex
package ships only the checksum manifest, and rockbox_ffi_nif.erl's -on_load
hook downloads the matching rockbox_ffi_nif-<triple>.so from the GitHub
release named in the manifest into the user cache on first use, verifying it
against the manifest sha256. This is why both the Elixir and Gleam bindings get
their native code the same way.
Local development
Inside a full monorepo checkout (needs the Cargo workspace + include/ header):
# 1. Build the Rust static archive.
cargo build --release -p rockbox-ffi
# 2. Build the NIF into priv/rockbox_ffi_nif.so.
cd bindings/erlang && make
# 3. Compile the Erlang app.
rebar3 compile
The Elixir/Gleam bindings pick up this locally-built .so via a path dependency
on ../erlang — the loader prefers a local priv/*.so over any cached download.
Supported prebuilt targets
aarch64-apple-darwin, x86_64-apple-darwin, aarch64-linux-gnu,
x86_64-linux-gnu, x86_64-unknown-freebsd, x86_64-unknown-netbsd.
Requires OTP 27+ (the bindings decode JSON with the built-in json module).
Other platforms build from source (steps above).