1# libz-sys
2
3A common library for linking `libz` to rust programs (also known as zlib).
4
5[Documentation](https://docs.rs/libz-sys)
6
7This also serves as the source for the `libz-ng-sys` crate, which builds
8zlib-ng natively (not in zlib-compat mode). See
9[`README-zng.md`](README-zng.md) for details.
10
11# High-level API
12
13This crate provides bindings to the raw low-level C API. For a higher-level
14safe API to work with DEFLATE, zlib, or gzip streams, see
15[`flate2`](https://docs.rs/flate2). `flate2` also supports alternative
16implementations, including slower but pure Rust implementations.
17
18# zlib-ng
19
20This crate supports building either the high-performance zlib-ng (in
21zlib-compat mode), or the widely available stock zlib.
22
23By default, `libz-sys` uses stock zlib, primarily because doing so allows the
24use of a shared system zlib library if available.
25
26Any application or library designed for zlib should work with zlib-ng in
27zlib-compat mode, as long as it doesn't make assumptions about the exact size
28or output of the deflated data (e.g. "compressing this data produces exactly
29this many bytes"), and as long as you don't also dynamically pull in a copy of
30stock zlib (which will produce conflicting symbols). Nonetheless, for maximum
31compatibility, every library crate in a build must opt into allowing zlib-ng;
32if any library crate in your dependency graph wants stock zlib, `libz-sys` will
33use stock zlib.
34
35Library crates depending on `libz-sys` should use:
36```
37libz-sys = { version = "1.1.0", default-features = false, features = ["libc"] }
38```
39(Omit the `libc` feature if you don't require the corresponding functions.)
40
41This allows higher-level crates depending on your library to opt into zlib-ng
42if desired.
43
44Building zlib-ng requires `cmake`.
45
46# License
47
48This project is licensed under either of
49
50 * Apache License, Version 2.0, ([LICENSE-APACHE](LICENSE-APACHE) or
51   http://www.apache.org/licenses/LICENSE-2.0)
52 * MIT license ([LICENSE-MIT](LICENSE-MIT) or
53   http://opensource.org/licenses/MIT)
54
55at your option.
56
57### Contribution
58
59Unless you explicitly state otherwise, any contribution intentionally submitted
60for inclusion in `libz-sys` by you, as defined in the Apache-2.0 license, shall be
61dual licensed as above, without any additional terms or conditions.
62