rust/crates/tinyquant-sys

This crate exposes a stable extern "C" ABI facade for non-Rust consumers of TinyQuant. All public entry points (tq_*) wrap their bodies in std::panic::catch_unwind so no panic ever crosses the boundary. Errors are surfaced via caller-owned TinyQuantError* out-pointers whose message field must be freed with tq_error_free. The C header include/tinyquant.h is regenerated by build.rs via cbindgen on every cargo build -p tinyquant-sys; CI fails on any non-empty diff (the Phase 22 cbindgen drift guard). See docs/design/rust/ffi-and-bindings.md §Binding 2 for the full design contract.

What lives here

• src/ — Rust source for the C ABI facade (see src/README.md).
• include/tinyquant.h — cbindgen-generated C header; do not edit by hand (see include/README.md).
• build.rs — drives cbindgen and post-processes the header to substitute the @version@ token with CARGO_PKG_VERSION.
• cbindgen.toml — cbindgen configuration; controls which types are exported and the header preamble.

How this area fits the system

tinyquant-sys is the C-ABI boundary. It depends on tinyquant-core and tinyquant-io for its implementation; all other crates in the workspace use the Rust-native APIs directly. The crate is #![no_std] (with extern crate alloc) and uses #![deny(unsafe_code)] at the root; the narrow modules codec_abi, corpus_abi, and error each carry an explicit #[allow(unsafe_code)] for the unavoidable pointer operations. A compile-time const block asserts TINYQUANT_H_VERSION matches CARGO_PKG_VERSION to catch stale headers.

Common edit paths

• src/codec_abi.rs — adding or changing codec-layer extern "C" entry points.
• src/corpus_abi.rs — adding corpus-layer entry points.
• cbindgen.toml — adjusting header preamble or export inclusions.
• include/tinyquant.h — regenerated automatically; commit the updated file after cargo build -p tinyquant-sys.

See also

• Parent README
• Local AGENTS.md