# Vendored C sources
Everything under this directory is third-party C source, copied verbatim from
upstream release artifacts. Nothing here is modified. `build.rs` compiles it
with the `cc` crate — there is no network access, no `curl`, no `tar`, no
`git`, no `cmake` and no process spawned at build time.
## Provenance
| Component | Version | Upstream artifact | SHA-256 of the tarball |
|---|---|---|---|
| OpenZL | tag `v0.3.0` = commit `32246b48faee46807f84183dac4db479089f5445` (2026-09-29) | `https://github.com/facebook/openzl/archive/refs/tags/v0.3.0.tar.gz` | `6e105e5c49187ebf63e0bf62fb3ecb22b628248c0bf55bd40ace434721f394f5` |
| zstd | 1.5.7 | `https://github.com/facebook/zstd/releases/download/v1.5.7/zstd-1.5.7.tar.gz` | `eb33e51f49a15e023950cd7825ca74a4a2b43db8354825ac24fc1b7ee09e6fa3` |
| lz4 | 1.10.0 | `https://github.com/lz4/lz4/releases/download/v1.10.0/lz4-1.10.0.tar.gz` | `537512904744b35e232912055ccf8ec66d768639ff3abe5788d90d792ec5f48b` |
The two dependency hashes are the ones OpenZL itself pins in
`build-scripts/cmake/openzl-deps.cmake` (`ZSTD_TARBALL_SHA256` line 27,
`LZ4_TARBALL_SHA256` line 114), so the vendored zstd and lz4 are exactly what
OpenZL's own CMake would have downloaded. v0.3.0 pins the same zstd 1.5.7 and
lz4 1.10.0 as the previous vendored commit, so `deps/` is unchanged. The OpenZL
hash is the GitHub tag tarball, downloaded 2026-10-02; `src/`, `include/`,
`LICENSE` and `CHANGELOG` were replaced from it and checked byte-identical.
## Which OpenZL each wrapper line bundles
The wrapper's version number is not OpenZL's. From 0.4.0 the crate version
carries the bundled OpenZL release as build metadata (`0.4.0+openzl.0.3.0`).
| openzl-sys-rs | OpenZL bundled | Library version | Frame formats | How |
|---|---|---|---|---|
| 0.1.0 (2026-05-21) | commit `ca28e4bc` | 0.2.1 | 8..=25 | downloaded at build time |
| 0.2.0 (2026-05-22) | commit `ca28e4bc` | 0.2.1 | 8..=25 | downloaded at build time |
| 0.3.0, 0.3.1 (2026-08) | commit `ca28e4bc` | 0.2.1 | 8..=25 | vendored |
| 0.4.0+openzl.0.3.0 | tag `v0.3.0` (`32246b48`) | 0.3.0 | 8..=27 | vendored |
OpenZL 0.3.0 writes frame format 27 by default (`ZL_getDefaultEncodingVersion`).
A reader built on any 0.1–0.3 wrapper decodes at most format 25, so a writer that
must stay readable by them sets `ZL_CParam_formatVersion` explicitly.
## Regenerating `src/bindings.rs`
The bindings are pre-generated so the crate needs no libclang. 0.4.0's were
produced with bindgen-cli 0.73.2 against libclang 21, from the crate root:
bindgen wrapper.h --allowlist-function 'ZL_.*' --allowlist-type 'ZL_.*' \
--allowlist-var 'ZL_.*' -o src/bindings.rs -- -I openzl/include -I openzl/src
(the same allowlist the 0.1.0 build-time bindgen used). API changes against the
0.3.x bindings: `ZL_MaterializerDesc2` is now `ZL_MaterializerDesc`,
`ZL_Compressor_registerBruteForceSelectorGraph` is replaced by
`ZL_Compressor_buildBruteForceSelectorGraph`, and new functions/types appear
(`ZL_Compressor_buildTrainableZstdGraph`, `ZL_Graph_getMParam`,
`ZL_Graph_getLocalParams`, `ZL_Edge_setEntropyDestination`, `ZL_E_clearInfo`,
`ZL_OperationContext_ownsError`, `ZL_LzParam`, `ZL_LzStrategy`,
`ZL_Result_uint{16,32,64}_t`). The crate's own helpers (`ZlCCtx`, `ZlDCtx`,
`zl_compress_bound`, `zl_decompress`, `zl_get_decompressed_size`) wrap none of
the renamed items and are unchanged; `ZL_COMPRESSBOUND` is identical in 0.3.0.
## What was and was not copied
* `src/`, `include/` — OpenZL, complete.
* `deps/zstd/lib/{common,compress,decompress,dictBuilder}` plus `zstd.h`,
`zstd_errors.h`, `zdict.h`. `lib/legacy` is omitted: OpenZL builds zstd with
`-DZSTD_LEGACY_SUPPORT=0`, so none of it is compiled.
* `deps/lz4/lib/*.{c,h}` — the library only. lz4's `programs/` (which is
GPL-2.0-or-later) is not vendored.
## Licences
* **OpenZL** — BSD-3-Clause. `openzl/LICENSE`, Meta Platforms, Inc.
* **zstd** — dual-licensed BSD-3-Clause / GPL-2.0. The BSD-3-Clause option is
elected here; `openzl/deps/zstd/LICENSE` is that text. Upstream's `COPYING`
(the GPL-2.0 alternative, which is not elected) is not redistributed.
* **lz4** — the vendored `lib/` directory is BSD-2-Clause;
`openzl/deps/lz4/LICENSE` is lz4's own `lib/LICENSE`. lz4's GPL-2.0-or-later
`programs/` tree is not vendored, so that licence does not apply to anything
shipped here.
The crate's package `license` field is therefore
`BSD-3-Clause AND BSD-2-Clause`.
## Build configuration reproduced by `build.rs`
Ported from what CMake actually put on the compiler command line. Taken from a
`compile_commands.json` of the 0.2.0 cmake build, not from reading the CMake by
eye.
| Target | Defines | Standard | Sources |
|---|---|---|---|
| `openzl` | `_GNU_SOURCE`, `_REENTRANT` | `gnu11` | `src/**/*.c` (279 files in v0.3.0) |
| `zstd` | `XXH_NAMESPACE=ZSTD_`, `ZSTD_LEGACY_SUPPORT=0`, `ZSTD_MULTITHREAD` | `gnu11` | `deps/zstd/lib/{common,compress,decompress,dictBuilder}/*.c` + `huf_decompress_amd64.S` |
| `lz4` | `XXH_NAMESPACE=LZ4_` | default | `deps/lz4/lib/*.c` |
`NDEBUG` is defined when `OPT_LEVEL != 0`, matching CMake's `Release`
configuration. Include order for `openzl` is: generated config dir, vendor
root, `include/`, `src/`, `deps/lz4/lib`, `deps/zstd/lib`.
### `zl_config.h`
Generated by `build.rs` into `OUT_DIR/include/openzl/zl_config.h`, reproducing
`configure_file(build-scripts/cmake/zl_config.h.cmake ...)`. Both knobs are 0:
* `ZL_ALLOW_INTROSPECTION` — 0.2.0 configured CMake with
`-DOPENZL_ALLOW_INTROSPECTION=OFF`.
* `ZL_HAVE_X86_64_ASM` — 0 *even on x86-64*. Upstream's
`OpenZLConfigChecks.cmake` sets a variable named `OPENZL_HAVE_X86_64_ASM`,
while both `zl_config.h.cmake` and `CMakeLists.txt` test
`ZL_HAVE_X86_64_ASM`, which nothing ever assigns. OpenZL's own
`huf_decompress_amd64.S` was consequently never compiled by the 0.2.0 build
either, and is not compiled here. This is upstream's bug, faithfully
preserved so the library behaves identically; it is not something this crate
should quietly "fix". v0.3.0 still has the same mismatch
(`OpenZLConfigChecks.cmake` line 6/13 vs `zl_config.h.cmake` line 16).
## System libraries
`m` and `pthread` on unix. 0.2.0 also emitted `-lstdc++`; it was never needed —
the `openzl` target is built with `OPENZL_BUILD_CPP=OFF` and is pure C, and
`nm --undefined-only libopenzl.a` reports zero C++ symbols. Dropping it removes
libstdc++ from this crate's build requirements.
## Escape hatch
Setting `OPENZL_SYS_LIB_DIR` to a directory containing `libopenzl.a`,
`libzstd.a` and `liblz4.a` links those instead of compiling the vendored tree.
The build script prints a line saying so, and fails loudly if any of the three
is absent rather than half-linking.