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 (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.

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:

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.