From 428dfbc4f5c1f6ca104907cfdb5df365b9ba613e Mon Sep 17 00:00:00 2001 From: ddidderr Date: Sat, 18 Jul 2026 18:56:29 +0200 Subject: [PATCH] docs(rust): refresh migration boundary Update the Rust rewrite documentation to match the current implementation boundary. The legacy decoder set is complete, and Rust now owns several CLI file-I/O policy and resource leaves while C retains format dispatch, metadata, and remaining orchestration. Keep the stated boundary explicit so passing hybrid tests do not imply that the full rewrite is finished. Test Plan: - git diff --cached --check --- rust/README.md | 39 ++++++++++++++++++++------------------- rust/src/zstd_cli.rs | 12 +++++++----- 2 files changed, 27 insertions(+), 24 deletions(-) diff --git a/rust/README.md b/rust/README.md index 810220176..34e629bf9 100644 --- a/rust/README.md +++ b/rust/README.md @@ -66,8 +66,9 @@ zstd ABI: - `zstd_ddict` owns, loads, copies, and references decode dictionaries. - Legacy decoding - `legacy` hosts one frozen module per historical format; `legacy::zstd_v01` - ports the self-contained v0.1 decoder. Versions v0.2 through v0.7 are - still C. + through `legacy::zstd_v07` port the seven self-contained historical + decoders. Their original C translation units remain declaration-only + shims for the native build. - Block decompression - `zstd_decompress_block` decodes literal and sequence sections, maintains FSE/Huffman repeat state, and executes compressed-block sequences. @@ -78,8 +79,10 @@ zstd ABI: - `zstd_cli` owns the Rust parser, safety policy, and dispatch. It is built by the separate `cli/` static-library package only for program archives, so library builds do not acquire program-only dependencies. The C - `fileio` backend still owns file opening, safe replacement, sparse writes, - metadata, and streaming I/O. + `fileio` layer still owns format-specific dispatch, metadata, and the + remaining C streaming/orchestration paths. Rust already owns the file + preference policy, filename decisions, source/destination opening, + dictionary buffers, asynchronous I/O pools, and pass-through copy leaf. - `timefn` provides the monotonic nanosecond clock behind `UTIL_time_t`, and `benchfn` owns the benchmark run/timing loop (`BMK_benchFunction`, `BMK_benchTimedFn`) used by the CLI benchmark mode and by C test tools. @@ -90,12 +93,12 @@ zstd ABI: orchestration and reporting (`benchzstd.c`) remain C, reached from the Rust parser through the `ZSTD_NOBENCH`-gated bridge in `zstdcli.c`. -The optimal block matcher, high-level frame compression, dictionary-building -except suffix-array construction, the legacy v0.2-v0.7 decoders, benchmark -orchestration (`benchzstd`), and the CLI file-I/O backend are still C. 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. +The optimal block matcher, most high-level frame-compression orchestration, +dictionary-building except suffix-array construction, benchmark orchestration +and reporting (`benchzstd`), and several format-specific CLI I/O paths are +still C. 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. ## Legacy decoding @@ -108,8 +111,8 @@ byte-identical to the original C files. Their only shared dependency is the `errors` module, matching the C files' `error_private.h` include. Cargo features `legacy-v01` .. `legacy-v07` gate the per-version modules and -are never default features. The build systems derive the feature list from -the C configuration: +are never default features. All seven modules are now available; the build +systems derive the enabled feature list from the C configuration: - `lib/Makefile` and `programs/Makefile` map `ZSTD_LEGACY_SUPPORT=N` to the features for versions >= N (0 disables legacy), matching the @@ -125,13 +128,11 @@ directory name (for example `c1-d1-default-legacy5`), for the same reason the HUF mode is encoded there: a cached archive built for one configuration must never be linked into a build that expects another. -A feature whose version has not been ported yet gates nothing; the original -C file still provides that decoder, so mixed C/Rust legacy levels link -cleanly. Porting a version means adding `src/legacy/zstd_v0N.rs`, registering -it in `src/legacy/mod.rs` behind its feature, and reducing -`lib/legacy/zstd_v0N.c` to a declaration-only shim. For v0.1 the streaming -`ZSTDv01_Dctx` state lives entirely in Rust: C code only ever holds an opaque -pointer, so the C-side struct definition is gone. +Each port adds `src/legacy/zstd_v0N.rs`, registers it in `src/legacy/mod.rs` +behind its feature, and reduces `lib/legacy/zstd_v0N.c` to a +declaration-only shim. For v0.1 the streaming `ZSTDv01_Dctx` state lives +entirely in Rust: C code only ever holds an opaque pointer, so the C-side +struct definition is gone. ## Compatibility boundary diff --git a/rust/src/zstd_cli.rs b/rust/src/zstd_cli.rs index 5af604de9..37d3e1ca8 100644 --- a/rust/src/zstd_cli.rs +++ b/rust/src/zstd_cli.rs @@ -4,11 +4,13 @@ //! Rust command-line frontend for zstd. //! -//! This is intentionally a parser and dispatch layer, not a second file I/O -//! implementation. It reuses the mature C `fileio` layer through its narrow -//! public-in-the-programs-tree ABI: file opening, safe replacement, sparse -//! writes, dictionary loading, streaming, and metadata preservation remain in -//! `programs/fileio.c` for this first migration step. +//! This is the Rust parser and dispatch layer plus selected file-I/O leaves, +//! not yet a fully independent file-I/O implementation. It shares the +//! mature C `fileio` layer through a narrow public-in-the-programs-tree ABI: +//! Rust owns preference policy, filename decisions, file opening, dictionary +//! loading, asynchronous pools, and pass-through copying, while C still owns +//! format-specific dispatch, metadata preservation, and remaining streaming +//! orchestration. //! //! Benchmark mode (`-b`) parses and dispatches through the Rust CLI archive. //! The bridge preserves the C CLI's argument normalization and uses the