Installation

Add the crate with Cargo:

cargo add stringzilla

Or declare it in Cargo.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:

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

Import items directly, or alias the crate as sz:

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) — 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.