Add `asio` cargo feature for optional ASIO support

ASIO introduces quite a few extra crates and requires a fairly
complicated setup process (see the readme), so this feature is disabled
by default.

Cargo.toml

@@ -8,6 +8,9 @@ documentation = "https://docs.rs/cpal"
 license = "Apache-2.0"
 keywords = ["audio", "sound"]
 
+[features]
+asio = ["asio-sys"] # Only available on Windows. See README for setup instructions.
+
 [dependencies]
 failure = "0.1.5"
 lazy_static = "1.3"
@@ -18,7 +21,7 @@ hound = "3.4"
 
 [target.'cfg(target_os = "windows")'.dependencies]
 winapi = { version = "0.3", features = ["audiosessiontypes", "audioclient", "coml2api", "combaseapi", "debug", "devpkey", "handleapi", "ksmedia", "mmdeviceapi", "objbase", "std", "synchapi", "winuser"] }
-asio-sys = { version = "0.1", path = "asio-sys" }
+asio-sys = { version = "0.1", path = "asio-sys", optional = true }
 
 [target.'cfg(any(target_os = "linux", target_os = "dragonfly", target_os = "freebsd", target_os = "openbsd"))'.dependencies]
 alsa-sys = { version = "0.1", path = "alsa-sys" }

README.md

@@ -83,7 +83,18 @@ WASAPI. To do so, follow these steps:
 
    If you run into an error along the lines of "no variant `Asio` in `HostId`",
    make sure that `CPAL_ASIO_DIR` is set correctly and try `cargo clean`.
+9. Make sure to enable the `asio` feature when building CPAL:
 
+   ```
+   cargo build --features "asio"
+   ```
+
+   or if you are using CPAL as a dependency in a downstream project, enable the
+   feature like this:
+
+   ```toml
+   cpal = { version = "*", features = ["asio"] }
+   ```
 
 In the future we would like to work on automating this process to make it
 easier, but we are not familiar enough with the ASIO license to do so yet.

src/host/mod.rs

@@ -1,6 +1,6 @@
 #[cfg(any(target_os = "linux", target_os = "freebsd"))]
 pub(crate) mod alsa;
-#[cfg(windows)]
+#[cfg(all(windows, feature = "asio"))]
 pub(crate) mod asio;
 #[cfg(any(target_os = "macos", target_os = "ios"))]
 pub(crate) mod coreaudio;

src/platform/mod.rs

@@ -521,6 +521,9 @@ mod platform_impl {
 // TODO: Add `Asio asio` once #221 lands.
 #[cfg(windows)]
 mod platform_impl {
+    #![allow(unreachable_patterns)]
+
+    #[cfg(feature = "asio")]
     pub use crate::host::asio::{
         Device as AsioDevice,
         Devices as AsioDevices,
@@ -540,8 +543,12 @@ mod platform_impl {
         SupportedOutputFormats as WasapiSupportedOutputFormats,
     };
 
+    #[cfg(feature = "asio")]
     impl_platform_host!(Asio asio, Wasapi wasapi);
 
+    #[cfg(not(feature = "asio"))]
+    impl_platform_host!(Wasapi wasapi);
+
     /// The default host for the current compilation target platform.
     pub fn default_host() -> Host {
         WasapiHost::new()