Switch to the Rust backend by default

alexcrichton · alexcrichton · commit c479d064e24c · 2019-10-01T07:37:15.000-07:00
Closes #215
diff --git a/.github/workflows/main.yml b/.github/workflows/main.yml
@@ -42,10 +42,10 @@ jobs:
     - run: rustdoc --test README.md -L target/debug/deps --extern flate2=target/debug/libflate2.rlib
     - run: cargo test
     - run: cargo test --features zlib
-    - run: cargo test --features tokio
-    - run: cargo test --features "tokio zlib"
+    - run: cargo test --features miniz-sys
     - run: cargo test --features zlib --no-default-features
     - run: cargo test --features miniz-sys --no-default-features
+    - run: cargo test --features tokio
 
   rustfmt:
     name: Rustfmt
@@ -77,18 +77,6 @@ jobs:
       run: rustup update stable && rustup default stable && rustup target add ${{ matrix.target }}
     - run: cargo build --target ${{ matrix.target }}
 
-  rust_backend:
-    name: Rust Backend
-    runs-on: ubuntu-latest
-    steps:
-    - uses: actions/checkout@master
-    - name: Install Rust
-      run: rustup update stable && rustup default stable
-    - run: cargo test --features rust_backend
-      continue-on-error: true
-    - run: cargo test --features rust_backend --no-default-features
-      continue-on-error: true
-
   publish_docs:
     name: Publish Documentation
     runs-on: ubuntu-latest
diff --git a/Cargo.toml b/Cargo.toml
@@ -41,7 +41,7 @@ tokio-threadpool = "0.1.10"
 futures = "0.1"
 
 [features]
-default = ["miniz-sys"]
+default = ["rust_backend"]
 zlib = ["libz-sys"]
 rust_backend = ["miniz_oxide"]
 tokio = ["tokio-io", "futures"]
diff --git a/README.md b/README.md
@@ -3,13 +3,11 @@
 [![Crates.io](https://img.shields.io/crates/v/flate2.svg?maxAge=2592000)](https://crates.io/crates/flate2)
 [![Documentation](https://docs.rs/flate2/badge.svg)](https://docs.rs/flate2)
 
-A streaming compression/decompression library for Rust. The underlying
-implementation by default uses [`miniz`](https://github.com/richgel999/miniz) but
-can optionally be configured to use the system zlib, if available.
+A streaming compression/decompression library DEFALTE-based streams in Rust.
 
-There is also an experimental rust backend that uses the
-[`miniz_oxide`](https://crates.io/crates/miniz_oxide) crate. This avoids the need
-to build C code, but hasn't gone through as much testing as the other backends.
+This crate by default implemented as a wrapper around the `miniz_oxide` crate, a
+port of `miniz.c` to Rust. This crate can also optionally use the zlib library
+or `miniz.c` itself.
 
 Supported formats:
 
@@ -23,25 +21,23 @@ Supported formats:
 flate2 = "1.0"
 ```
 
-Using zlib instead of miniz:
+Using zlib instead of the Rust backend:
 
 ```toml
 [dependencies]
 flate2 = { version = "1.0", features = ["zlib"], default-features = false }
 ```
 
-Using the rust back-end:
+Using `miniz.c`:
 
 ```toml
 [dependencies]
-flate2 = { version = "1.0", features = ["rust_backend"], default-features = false }
+flate2 = { version = "1.0", features = ["miniz-sys"], default-features = false }
 ```
 
 ## Compression
 
 ```rust
-extern crate flate2;
-
 use std::io::prelude::*;
 use flate2::Compression;
 use flate2::write::ZlibEncoder;
@@ -57,8 +53,6 @@ fn main() {
 ## Decompression
 
 ```rust,no_run
-extern crate flate2;
-
 use std::io::prelude::*;
 use flate2::read::GzDecoder;
 
diff --git a/src/lib.rs b/src/lib.rs
@@ -1,14 +1,42 @@
 //! A DEFLATE-based stream compression/decompression library
 //!
-//! This library is meant to supplement/replace the
-//! `flate` library that was previously part of the standard rust distribution
-//! providing a streaming encoder/decoder rather than purely
-//! an in-memory encoder/decoder.
-//!
-//! Like with [`flate`], flate2 is based on [`miniz.c`][1]
-//!
-//! [1]: https://github.com/richgel999/miniz
-//! [`flate`]: https://github.com/rust-lang/rust/tree/1.19.0/src/libflate
+//! This library provides support for compression and decompression of
+//! DEFLATE-based streams:
+//!
+//! * the DEFLATE format itself
+//! * the zlib format
+//! * gzip
+//!
+//! These three formats are all closely related and largely only differ in their
+//! headers/footers. This crate has three types in each submodule for dealing
+//! with these three formats.
+//!
+//! # Implementation
+//!
+//! In addition to supporting three formats, this crate supports three different
+//! backends, controlled through this crate's features:
+//!
+//! * `default`, or `rust_backend` - this implementation uses the `miniz_oxide`
+//!   crate which is a port of `miniz.c` (below) to Rust. This feature does not
+//!   require a C compiler and only requires Rust code.
+//!
+//! * `miniz-sys` - when enabled this feature will enable this crate to instead
+//!   use `miniz.c`, distributed with `miniz-sys`, to implement
+//!   compression/decompression.
+//!
+//! * `zlib` - finally, this feature will enable linking against the `libz`
+//!   library, typically found on most Linux systems by default. If the library
+//!   isn't found to already be on the system it will be compiled from source
+//!   (this is a C library).
+//!
+//! There's various tradeoffs associated with each implementation, but in
+//! general you probably won't have to tweak the defaults. The default choice is
+//! selected to avoid the need for a C compiler at build time. The `miniz-sys`
+//! feature is largely a historical artifact at this point and is unlikely to be
+//! needed, and `zlib` is often useful if you're already using `zlib` for other
+//! C dependencies. The compression ratios and performance of each of these
+//! feature should be roughly comparable, but you'll likely want to run your own
+//! tests if you're curious about the performance.
 //!
 //! # Organization
 //!
