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).

Note that we need both cfg(not(doc)) and
cfg(not(RUSTDOC_disable_compile_error)), 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,9 @@ repository = "https://github.com/rust-vmm/vhost"
 edition = "2021"
 license = "Apache-2.0"
 
+[package.metadata.docs.rs]
+all-features = true
+
 [features]
 xen = ["vm-memory/xen", "vhost/xen"]
 postcopy = ["vhost/postcopy", "userfaultfd"]
@@ -29,7 +32,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(RUSTDOC_disable_compile_error)'] }
+
 [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(RUSTDOC_disable_compile_error),
+    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

@@ -38,6 +38,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(RUSTDOC_disable_compile_error)'] }
+
 [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(RUSTDOC_disable_compile_error),
+    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