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