# lgz — guide
> **Class:** `guide` · **Function:** `lgz`. Build, run, tune. The shape is in
> [`lgz-design.md`](lgz-design.md); the why in [`lgz-reasoning.md`](lgz-reasoning.md).
## Build
```sh
CARGO_TARGET_DIR=/mnt/work4t/cargo-target/zoomies cargo build --release -p lgz
```
Binary lands at `target/release/lgz`.
## Run
```sh
lgz input.gz # → stdout (streaming, ordered)
lgz input.gz -o out # → file (positional pwrite fast path when multi-member)
lgz < input.gz > out # stdin (streaming only; no random-access fast path)
```
Any file `gzip`/`pigz` wrote decodes — lgz reads the stock format. A concatenated /
`--independent` / member-per-file `.tar.gz` takes the fully-parallel member path; a
`pigz` full-flush stream splits at flush points; a plain `gzip foo.gz` falls back to a
correct single-threaded decode (gzip's format has no interior split point — see
reasoning).
## Tune
- `LGZ_THREADS=N` pins the worker count (mirrors `LBZIP2_THREADS`). `LGZ_THREADS=1`
forces the single-worker `_st` bench row; unset ⇒ physical core count
(`lgz/src/bin/lgz.rs:100`, `physical_cores`).
- Watch `htop`: on a multi-member `-o` run cores should sit near-flat; a plain
single-member `.gz` will show one busy core (format-forced, not a bug).
## Library
```rust
// in-memory decode (parallel when large + flush points, else flate2):
let out = lgz::decompress_gz(&bytes)?; // lgz/src/parallel.rs:108
// bomb-safe capped decode (streaming, single-thread by design):
let out = lgz::decompress_gz_capped(&bytes, 64 << 20)?; // OUTPUT_TOO_LARGE on overflow
// tar.gz member filter:
let members = lgz::decompress_tar_gz_filter(&bytes, "config")?; // Vec<(name, bytes)>
```
## Bench
Driven by nornir through the shared harness — see
[`decompressors-guide.md`](decompressors-guide.md#run-the-heavy-bake-off). HEAVY only
(no smoke): `nornir bench run znippy-zoomies`, then `nornir docs book znippy-zoomies`
to fill the A/B/C mashup.