# graphblas-sys
Raw FFI bindings to **SuiteSparse:GraphBLAS**, our own bindgen output, linked
dynamically to the system `libgraphblas`. The safe layer is
[`nornir-mimir-graph`](https://crates.io/crates/nornir-mimir-graph) (`mimir_graph`).
Why our own: the published wrappers (`graphblas_sparse_linear_algebra`,
`suitesparse_graphblas_sys`) are CC-BY-NC-4.0. SuiteSparse:GraphBLAS itself is
Apache-2.0 (see `NOTICE`).
## Install the library
This crate does not build GraphBLAS: it links the system `libgraphblas`
(7.x) dynamically, so the library must be installed on the build machine and
on every machine that runs the binary.
```sh
sudo apt-get install -y libgraphblas-dev # Ubuntu: GraphBLAS 7.4.0
```
Found via `GRAPHBLAS_INCLUDE_DIR` / `GRAPHBLAS_LIB_DIR`, then
`pkg-config GraphBLAS` (upstream ships a `.pc` since 8.x; Ubuntu's 7.4 does
not), then `/usr/include`, `/usr/local/include`, `…/suitesparse`.
## Pregenerated bindings (default) vs `regenerate`
`src/bindings_7_4.rs` is checked in, generated from Ubuntu's `GraphBLAS.h`
7.4.0. A normal build needs **no libclang**: build machines and the test boxes
often lack it, and bindgen (+ clang-sys) costs ~4 min of build on a busy
12-core box. `build.rs` only links `-lgraphblas` and reads
`GxB_IMPLEMENTATION_MAJOR` from the header (plain text) — a header of a
different major version fails the build with a pointer to `regenerate`. The
safe layer also checks the *linked* library's version at `GrB_init`.
`--features regenerate` runs bindgen at build time (needs `libclang-dev`).
To refresh the checked-in file after a library upgrade:
```sh
cargo build -p graphblas-sys --features regenerate
cp target/debug/build/graphblas-sys-*/out/bindings.rs crates/graphblas-sys/src/bindings_7_4.rs
```
Allowlist: functions, vars and types matching `G[rx]B_.*`; `GB_*_opaque`
object structs (library-private) and libc `FILE` are emitted opaque.
## 7.4 (system) vs vendored 10.x — later decision
Nothing the lenses need today is missing in 7.4: CSR pack (zero-copy
ownership hand-over), iso builds (`GxB_Matrix_build_Scalar`), `GrB_Matrix_diag`,
ANY_PAIR / LOR_LAND / MIN_PLUS / MAX_SECOND / MIN_SECOND / PLUS_PAIR semirings,
complemented structural masks. So no vendored build now.
What a vendored upstream 10.x (cmake) would buy, and cost:
- **32-bit indices** (10.x stores `Ap`/`Aj` as 32-bit when they fit): halves
the CSR — at 10⁸ edges the matrix drops from ~0.8 GB to ~0.4 GB. The main
reason to move.
- **`GxB_Container`** (10.x) is the new zero-copy load/unload API; 7.4's
`GxB_Matrix_pack_CSR` already does the zero-copy hand-over we use.
- **`GrB_get` / `GrB_set`** (C API 2.1, GraphBLAS 9+) replace the variadic
`GxB_Global_Option_get/set` this crate uses for threads and version;
the old names are kept upstream as "historical" — check on regenerate.
- **JIT (8.0+)**: kernels for type/semiring combinations not in the
precompiled "FactoryKernels" are compiled at run time with the system C
compiler and cached (`~/.SuiteSparse`). A full FactoryKernels build is long
(upstream warns it can take tens of minutes on many cores; not measured
here); a `COMPACT` build skips them and relies on the JIT, which then needs
a C compiler on every box that runs a query the first time. For prebuilt
signed media without compilers that is a real cost; Ubuntu's prebuilt 7.4
has neither problem.
- LAGraph (FastSV components, direction-optimising BFS) is not needed: the
ops here are written directly on GraphBLAS.
Revisit when 10⁸+ edges make the 64-bit CSR memory matter, or when an op
needs something 7.4 lacks.
## Licence
The crate is MIT OR Apache-2.0. SuiteSparse:GraphBLAS is Apache-2.0,
Copyright Timothy A. Davis; the generated bindings come from its public
header (see `NOTICE`). No SuiteSparse source is vendored.