# Installation

> StringZilla for Rust

Add the crate with Cargo:

```sh
cargo add stringzilla
```

Or declare it in `Cargo.toml`:

```toml
[dependencies]
stringzilla = "6.0.0-rc.1"
```

The crate ships the C sources, and its `build.rs` builds them into `stringzilla_static` through CMake, so no system StringZilla install is required, but CMake and a C and C++ compiler are.
`STRINGZILLA_LIBRARY_DIR` names a directory holding a `stringzilla_static` CMake already built, like a parent project's build tree, and skips that build.

### Feature Flags

- `std`, on by default: `std` support, without which the crate is `no_std`.
- `cuda`: the CUDA backend, so `Capabilities::cuda_count_devices` counts devices and engines can be built on a `Stream` of `Capabilities::cuda_enabled(ordinal)`.
- `rocm`: the ROCm backend, compiled through HIP, so the `Capabilities::rocm_*` producers answer the same way.
- `metal`: the Metal backend on Apple platforms, linking the Metal and Foundation frameworks, so the `Capabilities::metal_*` producers answer the same way.

Every GPU feature implies `std`, which is also required for the `BuildSzHasher` integration with `HashMap`/`HashSet`.
Without one, the engines are host-only and every other verb is unchanged:

```toml
[dependencies]
stringzilla = { version = "6.0.0-rc.1", features = ["cuda"] } # CUDA-accelerated engines
```

Import items directly, or alias the crate as `sz`:

```rust
use stringzilla as sz;
use stringzilla::{StringZillableBinary, StringZillableUnary};
```

### SIMD Dispatch

Every call picks its kernel from the capability mask it passes, `Capabilities::cpu_enabled()` (see [Runtime Dispatch](https://www.unum.cloud/docs/stringzilla/rust/runtime-dispatch.md)) — the same `_best` dispatch points as the precompiled `stringzilla_shared` C library.
One binary runs optimally on any CPU of the target architecture, at the cost of one pick per operation.
CMake decides which capabilities to compile in, as for every other binding, by try-compiling `probes/<capability>.c` — tiny programs calling one of the capability's real kernels header-only at the baseline flags, so broken or old toolchains are caught up front.
Every capability the toolchain can emit is built, and the enabled mask leaves out whatever the CPU lacks.
Where the OS cannot be asked, as on OS-less targets, the CPU reports only the capabilities the C compiler's own flags guarantee.
A WebAssembly module carries the one SIMD kit the Rust target declares: `+relaxed-simd` gives `v128relaxed`, `+simd128` gives `v128`, and neither gives `serial`.

The build script forwards these environment variables to CMake, and rebuilds when one changes:

- `STRINGZILLA_TARGET_<CAPABILITY>`, like `STRINGZILLA_TARGET_SVE2=0 cargo build`, forces one capability on or off, though never past what the toolchain can compile.
- `STRINGZILLA_MARCH=native` tunes the library for the building machine, and `STRINGZILLA_MULTIVERSIONED=OFF` keeps only the capabilities it implies.
- `STRINGZILLA_CUDA_ARCH`, `STRINGZILLA_ROCM_ARCH` and `STRINGZILLA_METAL_ARCH` narrow the GPU code the features compile to one code, like `100f`.

An engine fixes its capability once, when it is constructed, and every round dispatches on that.

`use stringzilla::*;`

## version

Returns the semantic version information.

```rust
pub fn version() -> SemVer
```