Merge #54

54: Change default features r=Nemo157 a=Nemo157

Disables all features by default and updates documentation for them.

closes #46 

Co-authored-by: Wim Looman <[email protected]>

Author: bors[bot]

.travis.yml

@@ -6,7 +6,7 @@ rust:
 - nightly
 
 script:
-- cargo test --all
+- cargo test --all-features
 
 matrix:
   include:
@@ -23,16 +23,17 @@ matrix:
     - cargo update
     - cargo audit
 
-  - name: cargo build --features
+  - name: cargo check --features
     script:
     # Need to remove dev-dependencies so that they don't affect feature resolution
     - cargo run --manifest-path ci/remove-dev-dependencies/Cargo.toml
     # A somewhat arbitrary selection of features to check
-    - cargo build --no-default-features
-    - cargo build --no-default-features --features brotli,deflate,gzip,zlib,zstd,stream
-    - cargo build --no-default-features --features brotli,deflate,gzip,zlib,zstd,bufread
-    - cargo build --no-default-features --features brotli,bufread,stream
-    - cargo build --no-default-features --features zstd,bufread,stream
+    - cargo check
+    - cargo check --features brotli,deflate,gzip,zlib,zstd,stream
+    - cargo check --features brotli,deflate,gzip,zlib,zstd,bufread
+    - cargo check --features brotli,bufread,stream
+    - cargo check --features zstd,bufread,stream
+    - cargo check --features all
 
   - name: docs.rs
     rust: nightly
@@ -44,13 +45,13 @@ matrix:
     install:
     - rustup component add rustfmt
     script:
-    - cargo fmt --all -- --check
+    - cargo fmt -- --check
 
   - name: cargo clippy
     install:
     - rustup component add clippy
     script:
-    - cargo clippy --all --all-targets -- -D warnings
+    - cargo clippy --all-targets --all-features -- -D warnings
 
 branches:
   only: [staging, trying, master]

Cargo.toml

@@ -16,10 +16,18 @@ all-features = true
 rustdoc-args = ["--cfg", "docsrs"]
 
 [features]
-default = ["bufread", "stream", "write", "brotli", "bzip", "deflate", "gzip", "zlib", "zstd"]
+# groups
+default = []
+all = ["all-implementations", "all-algorithms"]
+all-implementations = ["bufread", "write", "stream"]
+all-algorithms = ["brotli", "bzip", "deflate", "gzip", "zlib", "zstd"]
+
+# implementations
 bufread = ["futures-io"]
 write = ["futures-io"]
 stream = ["bytes"]
+
+# algorithms
 brotli = ["brotli2"]
 bzip = ["bzip2"]
 deflate = ["flate2"]
@@ -47,3 +55,31 @@ futures = "0.3.0"
 futures-test = "0.3.0"
 ntest = "0.3.3"
 timebomb = "0.1.2"
+
+[[test]]
+name = "brotli"
+required-features = ["all-implementations", "brotli"]
+
+[[test]]
+name = "bzip"
+required-features = ["all-implementations", "bzip"]
+
+[[test]]
+name = "deflate"
+required-features = ["all-implementations", "deflate"]
+
+[[test]]
+name = "gzip"
+required-features = ["all-implementations", "gzip"]
+
+[[test]]
+name = "zlib"
+required-features = ["all-implementations", "zlib"]
+
+[[test]]
+name = "zstd"
+required-features = ["all-implementations", "zstd"]
+
+[[test]]
+name = "proptest"
+required-features = ["all"]

README.md

@@ -9,6 +9,13 @@ asynchronous IO types.
 - [Crates.io][2]
 - [Releases][releases]
 
+## Development
+
+When developing you will need to enable appropriate features for the different
+test cases to run, the simplest is `cargo test --all-features`, but you can
+enable different subsets of features as appropriate for the code you are
+testing to avoid compiling all dependencies.
+
 ## License
 
 Licensed under either of
@@ -26,14 +33,11 @@ additional terms or conditions.
 
 [1]: https://img.shields.io/crates/v/async-compression.svg?style=flat-square
 [2]: https://crates.io/crates/async-compression
-[3]: https://img.shields.io/travis/rustasync/async-compression/master.svg?style=flat-square
-[4]: https://travis-ci.org/rustasync/async-compression
+[3]: https://img.shields.io/travis/Nemo157/async-compression/master.svg?style=flat-square
+[4]: https://travis-ci.com/Nemo157/async-compression
 [5]: https://img.shields.io/crates/d/async-compression.svg?style=flat-square
 [6]: https://crates.io/crates/async-compression
 [7]: https://img.shields.io/badge/docs-latest-blue.svg?style=flat-square
 [8]: https://docs.rs/async-compression
 
-[releases]: https://github.com/rustasync/async-compression/releases
-[contributing]: https://github.com/rustasync/async-compression/blob/master.github/CONTRIBUTING.md
-[good-first-issue]: https://github.com/rustasync/async-compression/labels/good%20first%20issue
-[help-wanted]: https://github.com/rustasync/async-compression/labels/help%20wanted
+[releases]: https://github.com/Nemo157/async-compression/releases

src/lib.rs

@@ -1,23 +1,30 @@
 //! Adaptors between compression crates and Rust's modern asynchronous IO types.
 //!
-//!
+
 //! # Feature Organization
 //!
 //! This crate is divided up along two axes, which can each be individually selected via Cargo
 //! features.
 //!
-//! All features are default active, it's recommended you use this crate with `default-features =
-//! false` and enable just the features you need. (We're considering disabling this and shipping
-//! with no features active by default, please [leave a comment][#46] if you have an opinion either
-//! way).
+//! All features are disabled by default, you should enable just the ones you need from the lists
+//! below.
 //!
-//! [#46]: https://github.com/rustasync/async-compression/issues/46
+//! If you want to pull in everything there are three group features defined:
 //!
-//! ## IO type
+
+//!  Feature | Does
+//! ---------|------
+//!  `all`   | Activates all implementations and algorithms.
+//!  `all-implementations` | Activates all implementations, needs to be pared with a selection of algorithms
+//!  `all-algorithms` | Activates all algorithms, needs to be pared with a selection of implementations
 //!
-//! The first division is which underlying asynchronous IO type will be wrapped, these are
-//! available as two separate features that have corresponding top-level modules:
+
+//! ## IO implementation
 //!
+//! The first division is which underlying asynchronous IO trait will be wrapped, these are
+//! available as separate features that have corresponding top-level modules:
+//!
+
 //!  Feature | Type
 //! ---------|------
 // TODO: Kill rustfmt on this section, `#![rustfmt::skip::attributes(cfg_attr)]` should do it, but
@@ -47,24 +54,63 @@
     doc = "`stream` (*inactive*) | `futures::stream::Stream<Item = std::io::Result<bytes::Bytes>>`"
 )]
 //!
+
+//! ## Compression algorithm
 //!
-//! ## Compression implementation
-//!
-//! The second division is which compression scheme to use, there are currently a few available
-//! choices, these determine which types will be available inside the above modules:
+//! The second division is which compression schemes to support, there are currently a few
+//! available choices, these determine which types will be available inside the above modules:
 //!
-#![cfg_attr(feature = "brotli", doc = "* `brotli`")]
-#![cfg_attr(not(feature = "brotli"), doc = "* `brotli` (*inactive*)")]
-#![cfg_attr(feature = "bzip", doc = "* `bzip`")]
-#![cfg_attr(not(feature = "bzip"), doc = "* `bzip` (*inactive*)")]
-#![cfg_attr(feature = "deflate", doc = "* `deflate`")]
-#![cfg_attr(not(feature = "deflate"), doc = "* `deflate` (*inactive*)")]
-#![cfg_attr(feature = "gzip", doc = "* `gzip`")]
-#![cfg_attr(not(feature = "gzip"), doc = "* `gzip` (*inactive*)")]
-#![cfg_attr(feature = "zlib", doc = "* `zlib`")]
-#![cfg_attr(not(feature = "zlib"), doc = "* `zlib` (*inactive*)")]
-#![cfg_attr(feature = "zstd", doc = "* `zstd`")]
-#![cfg_attr(not(feature = "zstd"), doc = "* `zstd` (*inactive*)")]
+
+//!  Feature | Types
+//! ---------|------
+#![cfg_attr(
+    feature = "brotli",
+    doc = "`brotli` | [`BrotliEncoder`](?search=BrotliEncoder), [`BrotliDecoder`](?search=BrotliDecoder)"
+)]
+#![cfg_attr(
+    not(feature = "brotli"),
+    doc = "`brotli` (*inactive*) | `BrotliEncoder`, `BrotliDecoder`"
+)]
+#![cfg_attr(
+    feature = "bzip",
+    doc = "`bzip` | [`BzEncoder`](?search=BzEncoder), [`BzDecoder`](?search=BzDecoder)"
+)]
+#![cfg_attr(
+    not(feature = "bzip"),
+    doc = "`bzip` (*inactive*) | `BzEncoder`, `BzDecoder`"
+)]
+#![cfg_attr(
+    feature = "deflate",
+    doc = "`deflate` | [`DeflateEncoder`](?search=DeflateEncoder), [`DeflateDecoder`](?search=DeflateDecoder)"
+)]
+#![cfg_attr(
+    not(feature = "deflate"),
+    doc = "`deflate` (*inactive*) | `DeflateEncoder`, `DeflateDecoder`"
+)]
+#![cfg_attr(
+    feature = "gzip",
+    doc = "`gzip` | [`GzipEncoder`](?search=GzipEncoder), [`GzipDecoder`](?search=GzipDecoder)"
+)]
+#![cfg_attr(
+    not(feature = "gzip"),
+    doc = "`gzip` (*inactive*) | `GzipEncoder`, `GzipDecoder`"
+)]
+#![cfg_attr(
+    feature = "zlib",
+    doc = "`zlib` | [`ZlibEncoder`](?search=ZlibEncoder), [`ZlibDecoder`](?search=ZlibDecoder)"
+)]
+#![cfg_attr(
+    not(feature = "zlib"),
+    doc = "`zlib` (*inactive*) | `ZlibEncoder`, `ZlibDecoder`"
+)]
+#![cfg_attr(
+    feature = "zstd",
+    doc = "`zstd` | [`ZstdEncoder`](?search=ZstdEncoder), [`ZstdDecoder`](?search=ZstdDecoder)"
+)]
+#![cfg_attr(
+    not(feature = "zstd"),
+    doc = "`zstd` (*inactive*) | `ZstdEncoder`, `ZstdDecoder`"
+)]
 //!
 
 #![cfg_attr(docsrs, feature(doc_cfg))]

tests/bzip2.rs renamed to tests/bzip.rs

@@ -1,4 +1,4 @@
 #[macro_use]
 mod utils;
 
-test_cases!(bzip2);
+test_cases!(bzip);

tests/proptest.rs

@@ -74,4 +74,4 @@ macro_rules! tests {
     }
 }
 
-tests!(brotli, bzip2, deflate, gzip, zlib, zstd);
+tests!(brotli, bzip, deflate, gzip, zlib, zstd);

tests/utils/mod.rs

@@ -190,7 +190,7 @@ pub mod brotli {
     }
 }
 
-pub mod bzip2 {
+pub mod bzip {
     pub mod sync {
         use crate::utils::prelude::*;