# Language bindings

snapdir ships official bindings for six languages plus a native Rust API. Every
binding wraps the same Rust core, so the manifests and snapshot IDs they produce
are bit-identical to the CLI — a `<snapshot-id>` computed in Node, Python, or Go
is the exact 64-character lowercase hex string you get from `snapdir id`.

The surface is the same everywhere: synchronous `id` / `manifest`, plus async
`push` / `pull` / `fetch` / `diff` / `sync`, expressed in each language's idiom.
Errors share one stable 8-code taxonomy — `IO_ERROR`, `HASH_MISMATCH`,
`STORE_ERROR`, `IN_FLUX`, `CATALOG_ERROR`, `INVALID_ID`, `INVALID_STORE`, and
`CONFLICT` — so error handling ports cleanly from one language to the next.

## Choose your language

| Language | Binding | Install |
| --- | --- | --- |
| [Node.js](/bindings/node/) | `@snapdir/snapdir` | `npm install @snapdir/snapdir` |
| [Python](/bindings/python/) | `snapdir` | `pip install snapdir` |
| [Go](/bindings/go/) | `github.com/snapdir/snapdir/bindings/go` | `go get github.com/snapdir/snapdir/bindings/go` |
| [Java](/bindings/java/) | `org.snapdir:snapdir` | Maven/Gradle `org.snapdir:snapdir` |
| [C/C++](/bindings/cpp/) | `snapdir-ffi` + `snapdir.hpp` | build the `snapdir-ffi` crate, include `snapdir.hpp` |
| [Zig](/bindings/zig/) | `snapdir-ffi` + Zig wrapper | build the `snapdir-ffi` crate, `zig fetch --save` the wrapper |
| [Rust](/bindings/rust/) | `snapdir-api` | `cargo add snapdir-api` |

## Two install shapes

Bindings come in two flavors depending on how the native code is delivered:

- **Prebuilt, zero-compiler** — Node, Python, and Java ship precompiled native
  binaries in their published packages. Install from the registry and you are
  done; no Rust toolchain or C compiler required.
- **Build-from-source** — C/C++, Zig, and Go build against the `snapdir-ffi`
  C ABI. You compile the `snapdir-ffi` crate (from crates.io) and generate its
  header with `cbindgen`, then link your program against it. A Rust toolchain
  and a C toolchain are required.

## Platform support

Every binding is CI-verified against its live public registry before release.

| Binding | Linux glibc | Linux musl (Alpine) | macOS | Windows |
| --- | --- | --- | --- | --- |
| Node.js | yes (x64 + arm64) | yes (x64 + arm64) | yes | no |
| Python | yes (x64 + arm64) | yes (x64 + arm64) | yes | no |
| Go | yes (x64 + arm64) | yes (x64 + arm64) | yes | no |
| Java | yes (x64 + arm64) | no (planned 1.11.1) | yes | no |
| C/C++ | yes (x64 + arm64) | yes (x64 + arm64) | yes | no |
| Zig | yes (x64 + arm64) | yes (x64 + arm64) | yes | no |
| Rust | yes (x64 + arm64) | yes (x64 + arm64) | yes | no |

All bindings run on Linux (glibc and Alpine/musl, x64 and arm64) and macOS. The
one exception is Java, which is glibc-only today — musl support is planned for
1.11.1. Windows is unsupported: snapdir is Unix-only.