# 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`](src/README.md)).
- `include/tinyquant.h` — cbindgen-generated C header; do not edit by hand (see [`include/README.md`](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](../README.md)
- [Local AGENTS.md](./AGENTS.md)