# Rust rewrite

This directory contains the in-progress Rust replacement for the zstd library
and command-line program. During the migration, the crate is built as a static
library and linked into the original C test programs. Production C translation
units become declaration-only shims as their implementations move to Rust; the
original C tests remain unchanged and provide compatibility coverage.

## Component map

The crate is organized from low-level representation helpers toward the public
zstd ABI:

- Common primitives
  - `mem`, `bits`, `bitstream`, and `cpu` implement byte-order, bitstream, and
    target-feature operations used by the codecs.
  - `errors`, `debug`, `xxhash`, and `zstd_common` provide common exported ABI
    functions and state.
  - `common` contains shared frame constants and internal data types.
All entropy coding, compression, decompression, dictionary, legacy, runtime,
and CLI translation units are still C at this initial stage. They must move
before the rewrite is complete. Keeping that boundary explicit prevents a
passing hybrid build from being mistaken for the final all-Rust result.

## Compatibility boundary

The public ABI continues to come from the existing headers under `lib/`.
Exported Rust functions therefore use C layout and calling conventions. A C
source file whose implementation has moved to Rust remains in the original
makefile source list as a small shim so header configuration and platform
preprocessor behavior stay available during the transition.

The original test makefile links `target/release/libzstd_rs.a` with whole-archive
semantics. Rebuild the Rust archive before running C tests so the executable
does not use a stale implementation.

## Validation

Run focused Rust checks from this directory:

```sh
cargo fmt --check
cargo clippy --all-targets -- -D warnings
cargo test --all-targets
cargo build --release
```

Then run original compatibility tests from the repository root, starting with
the narrow target for the component being migrated. For example:

```sh
make -C tests fuzzer
./tests/fuzzer -i1 --no-big-tests
```

Broader `tests/Makefile` targets remain the authoritative integration gates as
more of the library and CLI are rewritten.