Add a compile_error!() when central crate features clash

README.md

@@ -7,28 +7,33 @@
 This crate provides safe bindings to the Video for Linux (V4L) stack. Modern device drivers will usually implement the `v4l2` API while older ones may depend on the legacy `v4l` API. Such legacy devices may be used with this crate by choosing the `libv4l` feature for this crate.
 
 ## Goals
-This crate shall provide the v4l-sys package to enable full (but unsafe) access to libv4l\*.
-On top of that, there will be a high level, more idiomatic API to use video capture devices in Linux.
+
+This crate shall provide the `v4l-sys` package to enable full (but unsafe) access to `libv4l\*`.
+On top of that, there will be a high level, more idiomatic API to use video capture devices on Linux.
 
 There will be simple utility applications to list devices and capture frames.
 A minimalistic OpenGL/Vulkan viewer to display frames is planned for the future.
 
 ## Changelog
+
 See [CHANGELOG.md](https://github.com/raymanfx/libv4l-rs/blob/master/CHANGELOG.md)
 
-## Dependencies
-You have the choice between two dependencies (both provided by this crate internally):
- * libv4l-sys
-   > Link against the libv4l* stack including libv4l1, libv4l2, libv4lconvert.
-   > This has the advantage of emulating common capture formats such as RGB3 in userspace through libv4lconvert and more.
-   > However, some features like userptr buffers are not supported in libv4l.
- * v4l2-sys
-   > Use only the Linux kernel provided v4l2 API provided by videodev2.h.
-   > You get support for all v4l2 features such as userptr buffers, but may need to do format conversion yourself if you require e.g. RGB/BGR buffers which may not be supported by commodity devices such as webcams.
+## Cargo Features
+
+This crate has two primary features:
 
-Enable either the `libv4l` or the `v4l2` backend by choosing the it as feature for this crate.
+* `libv4l`: uses the `libv4l` wrapper libraries.
+  * Links against the `libv4l*` stack, including `libv4l1`, `libv4l2`, and `libv4lconvert`.
+  * Has the advantage of emulating common capture formats such as RGB3 in userspace through `libv4lconvert` and more.
+  * However, some features, like `userptr` buffers, are not supported in `libv4l`.
+* `v4l2` (DEFAULT): uses the kernel's Video4Linux 2 kernel header directly.
+  * Only uses the Linux kernel provided v4l2 API provided by `videodev2.h`.
+  * You get support for all v4l2 features such as `userptr` buffers, but may need to do format conversion yourself if you require certain constructs (e.g. RGB/BGR buffers), which may not be supported by commodity devices such as webcams.
+
+You must select exactly one of these features. Note that the `v4l2` feature is on by default. To use `libv4l` instead, you'll need to also use the `default-features = false` dependency key.
 
 ## Usage
+
 Below you can find a quick example usage of this crate. It introduces the basics necessary to do frame capturing from a streaming device (e.g. webcam).
 
 ```rust
@@ -93,4 +98,4 @@ fn main() {
 }
 ```
 
-Have a look at the provided `examples` for more sample applications.
+Have a look at the provided [`examples`](./examples/) for more sample applications.

src/lib.rs

@@ -67,12 +67,25 @@
 //!
 //! Have a look at the examples to learn more about device and buffer management.
 
-#[cfg(feature = "v4l-sys")]
+#[cfg(all(feature = "libv4l", feature = "v4l2"))]
+compile_error!(
+    "You may not enable both `v4l-sys` and `v4l2-sys` features at the same time.\
+    Try disabling one of them. If you only specified one feature, you may wish to\
+    add `default-features = false` as a dependency key."
+);
+
+#[cfg(all(feature = "libv4l", not(feature = "v4l2")))]
 pub use v4l_sys;
 
-#[cfg(feature = "v4l2-sys")]
+#[cfg(all(feature = "v4l2", not(feature = "libv4l")))]
 pub use v4l2_sys as v4l_sys;
 
+// calms down rust-analyzer when `rust-analyzer.cargo.features = "all"`,
+// though the `compile_error!()` above prevents this from being a valid,
+// compilable configuration.
+#[cfg(all(feature = "v4l2", feature = "libv4l"))]
+pub use v4l_sys;
+
 pub mod v4l2;
 
 pub mod buffer;

src/v4l2/api.rs

@@ -4,7 +4,7 @@ use std::{io, path::Path};
 
 use crate::v4l2::vidioc;
 
-#[cfg(feature = "v4l-sys")]
+#[cfg(all(feature = "libv4l", not(feature = "v4l2")))]
 mod detail {
     use crate::v4l2::vidioc;
     use crate::v4l_sys::*;
@@ -56,7 +56,7 @@ mod detail {
     }
 }
 
-#[cfg(feature = "v4l2-sys")]
+#[cfg(feature = "v4l2")]
 mod detail {
     use crate::v4l2::vidioc;