fix cargo doc

Introduce a dummy feature to hack around `cargo doc --all-features`
always hitting the compile_error!(...) in vhost/src/lib.rs about
incompatible features.

This is happening because when documenting vhost-user-backend, cargo
does not pass --cfg doc to dependencies, meaning the cfg(not(doc))
attribute that is supposed to eliminate this compile_error!() invokation
when building docs does not actually trigger. Hence cargo doc fails.

Introduce a custom cfg, which we tell docs.rs to set during
documentation build, which disables the compile_error!(). Our CI also
sets this flag for the rustdoc step (via an ugly `sed` in the pipeline
definition). This cfg is also set by rust-vmm-ci for the cargo doc step.

Note that we need both cfg(not(doc)) and
cfg(not(RUTSDOC_disable_feature_compat_errors)), because lib.rs gets
processed twice, onces by rustc (where the --cfg is passed via
RUSTFLAGS), and once by rustdoc itself, where RUSTFLAGS are ignored, and
instead the cfg(doc) macro comes into play (but rustdoc is only ran on
the crate for which we are actually generating docs, not the
dependencies).

Signed-off-by: Patrick Roy <[email protected]>

Author: roypat

vhost-user-backend/Cargo.toml

@@ -8,6 +8,10 @@ repository = "https://github.com/rust-vmm/vhost"
 edition = "2021"
 license = "Apache-2.0"
 
+[package.metadata.docs.rs]
+all-features = true
+rustc-args  = ['--cfg RUTSDOC_disable_feature_compat_errors']
+
 [features]
 xen = ["vm-memory/xen", "vhost/xen"]
 postcopy = ["vhost/postcopy", "userfaultfd"]
@@ -29,7 +33,10 @@ vhost = { path = "../vhost", version = "0.14.0", features = ["test-utils", "vhos
 vm-memory = { workspace = true, features = ["backend-mmap", "backend-atomic"] }
 tempfile = "3.2.0"
 
+[lints.rust]
+unexpected_cfgs = { level = "warn", check-cfg = ['cfg(RUTSDOC_disable_feature_compat_errors)'] }
+
 [package.metadata.cargo-all-features]
 skip_feature_sets = [
     ["xen", "postcopy"]
-]
+]

vhost-user-backend/src/lib.rs

@@ -36,10 +36,15 @@ pub use self::vring::{
     VringMutex, VringRwLock, VringState, VringStateGuard, VringStateMutGuard, VringT,
 };
 
-/// Due to the way `xen` handles memory mappings we can not combine it with
-/// `postcopy` feature which relies on persistent memory mappings. Thus we
-/// disallow enabling both features at the same time.
-#[cfg(all(feature = "postcopy", feature = "xen"))]
+// Due to the way `xen` handles memory mappings we can not combine it with
+// `postcopy` feature which relies on persistent memory mappings. Thus we
+// disallow enabling both features at the same time.
+#[cfg(all(
+    not(RUTSDOC_disable_feature_compat_errors),
+    not(doc),
+    feature = "postcopy",
+    feature = "xen"
+))]
 compile_error!("Both `postcopy` and `xen` features can not be enabled at the same time.");
 
 /// An alias for `GuestMemoryAtomic<GuestMemoryMmap<B>>` to simplify code.

vhost/Cargo.toml

@@ -12,6 +12,7 @@ edition = "2021"
 
 [package.metadata.docs.rs]
 all-features = true
+rustc-args  = ['--cfg RUTSDOC_disable_feature_compat_errors']
 
 [features]
 default = []
@@ -38,6 +39,9 @@ vm-memory = { workspace = true, features=["backend-mmap"] }
 tempfile = "3.2.0"
 serial_test = "3.0"
 
+[lints.rust]
+unexpected_cfgs = { level = "warn", check-cfg = ['cfg(RUTSDOC_disable_feature_compat_errors)'] }
+
 [package.metadata.cargo-all-features]
 skip_feature_sets = [
     ["xen", "postcopy"]

vhost/src/lib.rs

@@ -51,10 +51,15 @@ pub mod vhost_user;
 #[cfg(feature = "vhost-vsock")]
 pub mod vsock;
 
-/// Due to the way `xen` handles memory mappings we can not combine it with
-/// `postcopy` feature which relies on persistent memory mappings. Thus we
-/// disallow enabling both features at the same time.
-#[cfg(all(not(doc), feature = "postcopy", feature = "xen"))]
+// Due to the way `xen` handles memory mappings we can not combine it with
+// `postcopy` feature which relies on persistent memory mappings. Thus we
+// disallow enabling both features at the same time.
+#[cfg(all(
+    not(RUTSDOC_disable_feature_compat_errors),
+    not(doc),
+    feature = "postcopy",
+    feature = "xen"
+))]
 compile_error!("Both `postcopy` and `xen` features can not be enabled at the same time.");
 
 /// Error codes for vhost operations