Skip to content

feat: add linker args for VHF lib to wdk-build #653

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
Alan632 wants to merge 13 commits into
base: main
Choose a base branch
from
Open

feat: add linker args for VHF lib to wdk-build #653

Changes from 11 commits
Commits
Show all changes
13 commits
Select commit Hold shift + click to select a range
294c27e
initial commit - add vhf lib link emission to wdk-build
Apr 30, 2026
b194380
remove wdk-sys feature flag forward
May 1, 2026
cfae425
add comments to linker emissions for vhf lib
May 1, 2026
70305e3
Merge branch 'microsoft:main' into vhf_lib_linker_args
Alan632 May 1, 2026
4427c85
redesigned wdk-build build script output linking vhf to use cargo met…
May 6, 2026
7fc834a
formatting
May 6, 2026
74ebe7c
changed how the "hid" feature is checked in configure_binary_build
May 6, 2026
6bdb8e3
changed Config's enabled_api_subsets member to utilize the type safe …
May 7, 2026
8ff9e5b
added serde attribute to Config member for deserialize compatibility
May 7, 2026
0d8fe7f
extended config unit tests to include new member
May 8, 2026
18d42f3
refactor api_subsets search to use match, refactor hid api check to u…
May 8, 2026
55a63a1
refactored feature filter to skip json and use ApiSubset deserializer…
May 9, 2026
d22d9db
add error to panic message
May 9, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
75 changes: 74 additions & 1 deletion crates/wdk-build/src/lib.rs
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -31,6 +31,7 @@ mod bindgen;

use cargo_metadata::MetadataCommand;
use serde::{Deserialize, Serialize};
use serde_json::{Value, from_value};
use thiserror::Error;

use crate::utils::detect_windows_sdk_version;
Expand All @@ -45,6 +46,9 @@ pub struct Config {
cpu_architecture: CpuArchitecture,
/// Build configuration of driver
pub driver_config: DriverConfig,
/// List of features enabled for `wdk-sys` in resolved dependency graph
Comment thread
Alan632 marked this conversation as resolved.
#[serde(default)]
Copy link
Copy Markdown
Collaborator

@wmmc88 wmmc88 May 8, 2026 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Drop #[serde(default)] here. Nothing in the repo actually deserializes Config (all instances come from from_env_auto/new/default/struct literals; the line 554 serialization is metadata::Wdk, not Config), so this attribute has no observable effect today and implies a backwards-compat invariant the codebase doesn't uphold.

Copy link
Copy Markdown
Contributor Author

@Alan632 Alan632 May 9, 2026 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Sounds good and done! I didn't think about what could be implied (the backwards-compat invariant) by adding that attribute.

enabled_api_subsets: Vec<ApiSubset>,
Copy link
Copy Markdown
Collaborator

@wmmc88 wmmc88 May 8, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This should be a BTreeSet<ApiSubset> rather than a Vec. Each variant should appear at most once, and the three call sites that do iter().any(|f| f == &ApiSubset::Hid) collapse to contains(&ApiSubset::Hid). BTreeSet over HashSet keeps Config's Serialize/Deserialize round-trips deterministic (although we dont actually use this right now)

Copy link
Copy Markdown
Contributor Author

@Alan632 Alan632 May 9, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Done!

}

/// The driver type with its associated configuration parameters
Expand Down Expand Up @@ -316,7 +320,8 @@ rustflags = [\"-C\", \"target-feature=+crt-static\"]
}

/// Subset of APIs in the Windows Driver Kit
#[derive(Debug, Copy, Clone, PartialEq, Eq)]
#[derive(Debug, Copy, Clone, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "kebab-case")]
pub enum ApiSubset {
/// API subset typically required for all Windows drivers
Base,
Expand Down Expand Up @@ -397,6 +402,7 @@ impl Default for Config {
),
driver_config: DriverConfig::Wdm,
cpu_architecture: utils::detect_cpu_architecture_in_build_script(),
enabled_api_subsets: Vec::new(),
}
}
}
Expand Down Expand Up @@ -447,6 +453,41 @@ impl Config {
.exec()?;
let wdk_metadata = metadata::Wdk::try_from(&cargo_metadata)?;

// Find the `wdk-sys` package's PackageId in `cargo_metadata`
let wdk_sys_package_id = cargo_metadata
.packages
.iter()
.find(|pkg| pkg.name == "wdk-sys")
.map(|pkg| &pkg.id);
// Extract the features enabled for `wdk-sys`
// Produces an empty Vec if `wdk-sys` is not found in the dependency graph
let wdk_sys_enabled_features = match wdk_sys_package_id {
None => {
// wdk-sys not in dependency graph
Vec::new()
}
Some(id) => cargo_metadata
.resolve
.as_ref()
.and_then(|resolve| resolve.nodes.iter().find(|node| node.id == *id))
.map_or_else(
Comment thread
wmmc88 marked this conversation as resolved.
Outdated
Copy link
Copy Markdown
Collaborator

@wmmc88 wmmc88 May 8, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This shouldn't be a warning. Two coherent options: (1) if wdk-sys missing from the build graph is invalid, return a ConfigError from from_env_auto() on None for wdk_sys_package_id so the build fails fast instead of silently omitting feature-gated linker args; (2) if it's a valid state, drop the warning entirely.

(2) is the right call. wdk-build can legitimately be consumed without wdk-sys -- for example, a crate that only wants the cfg plumbing it emits (driver_model__driver_type, driver_model__kmdf_version_major, etc.) without pulling in the FFI bindings (think a higher-level safe wrapper that re-exports from a separately-versioned wdk-sys, or a utility crate that just gates code on driver type). In that case enabled_api_subsets correctly should be empty and from_env_auto() should succeed silently -- the warning is flagging a valid usage pattern as if it were broken.

Copy link
Copy Markdown
Contributor Author

@Alan632 Alan632 May 9, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

That makes sense, we now use expect to panic in case of a true build error.

|| {
tracing::warn!(
"wdk-sys was found in packages but its features could not be \
determined from cargo metadata resolve. Feature-dependent libraries \
will not be linked automatically."
);
Vec::new()
Copy link
Copy Markdown
Collaborator

@wmmc88 wmmc88 May 8, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

the per-feature from_value(Value::String(f.clone())) is doing an unnecessary JSON round-trip and allocates/clones for every feature. Driving ApiSubset's existing Deserialize impl directly from &str via serde::de::IntoDeserializer avoids both:

use serde::de::{IntoDeserializer, value::{Error as ValueError, StrDeserializer}};

node.features
    .iter()
    .filter_map(|f| {
        ApiSubset::deserialize(f.as_str().into_deserializer()).ok()
    })
    .collect()

Copy link
Copy Markdown
Collaborator

@wmmc88 wmmc88 May 8, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

actually, this should go further and actually filter some known set of cargo features that aren't APISubsets (ie. default, nightly), instead of relying on a deserialization failure

Copy link
Copy Markdown
Contributor Author

@Alan632 Alan632 May 8, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

To clarify the second point - is the desire to have a set of known features (aka all wdk-sys features) and warn the user if something not in that set is found in the metadata?

If we have a set of known "non ApiSubset" features that we filter out without notifying the user about it, then that sounds similar to silently filtering out via deserialization failure?

Copy link
Copy Markdown
Collaborator

@wmmc88 wmmc88 May 8, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

we'd have a set of known non-api-subset features, and if we encounter one of those, it should hard error. anything thats not an api-subset feature and not in the known list should be treated as an unknown feature and we should bail. this is to help make sure at compile time that when there are new api subsets added, they map cleanly to the enum

Copy link
Copy Markdown
Contributor Author

@Alan632 Alan632 May 9, 2026 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

wait, we should hard error on encountering non-api-subset features? (aka default, nightly, test-stubs) Shouldn't we just filter those out and only hard error on anything that isn't listed in the [features] section in wdk-sys's Cargo.toml? Otherwise build will fail if we enable a feature like default or nightly in wdk-sys

Copy link
Copy Markdown
Contributor Author

@Alan632 Alan632 May 9, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I went ahead and changed the implementation to hard error on found features that are neither in the non-api-subset-features list and the ApiSubset enum (eg. an unknown 'new' feature from wdk-sys), which I think is what we're both trying to express 😅 let's discuss offline if needed!

},
|node| {
node.features
.iter()
.filter_map(|f| from_value::<ApiSubset>(Value::String(f.clone())).ok())
.collect()
},
),
};

// Force rebuilds if any of the manifest files change (ex. if wdk metadata
// section is modified)
for manifest_path in metadata::iter_manifest_paths(cargo_metadata)
Expand All @@ -462,6 +503,7 @@ impl Config {

Ok(Self {
driver_config: wdk_metadata.driver_model,
enabled_api_subsets: wdk_sys_enabled_features,
..Default::default()
})
}
Expand Down Expand Up @@ -1157,6 +1199,13 @@ impl Config {
// provides no way to set a symbol's name without also exporting the symbol:
// https://github.com/rust-lang/rust/issues/67399
println!("cargo::rustc-cdylib-link-arg=/IGNORE:4216");

// Link against VhfKm.lib (Virtual HID Framework, kernel-mode) when
// the "hid" feature is enabled in wdk-sys. Required by drivers that
// create virtual HID devices.
if self.enabled_api_subsets.contains(&ApiSubset::Hid) {
println!("cargo::rustc-cdylib-link-arg=VhfKm.lib");
Comment on lines +1222 to +1226
}
}
DriverConfig::Kmdf(_) => {
// Emit KMDF-specific libraries to link to
Expand Down Expand Up @@ -1186,6 +1235,13 @@ impl Config {
// Ignore `LNK4257: object file was not compiled for kernel mode; the image
// might not run` since `rustc` has no support for `/KERNEL`
println!("cargo::rustc-cdylib-link-arg=/IGNORE:4257");

// Link against VhfKm.lib (Virtual HID Framework, kernel-mode) when
// the "hid" feature is enabled in wdk-sys. Required by drivers that
// create virtual HID devices.
if self.enabled_api_subsets.contains(&ApiSubset::Hid) {
println!("cargo::rustc-cdylib-link-arg=VhfKm.lib");
Comment on lines +1258 to +1262
}
Comment thread
Alan632 marked this conversation as resolved.
}
DriverConfig::Umdf(umdf_config) => {
// Emit UMDF-specific libraries to link to
Expand All @@ -1200,6 +1256,13 @@ impl Config {

// Linker arguments derived from WindowsDriver.UserMode.props in Ni(22H2) WDK
println!("cargo::rustc-cdylib-link-arg=/SUBSYSTEM:WINDOWS");

// Link against VhfUm.lib (Virtual HID Framework, user-mode) when
// the "hid" feature is enabled in wdk-sys. Required by drivers that
// create virtual HID devices.
if self.enabled_api_subsets.contains(&ApiSubset::Hid) {
println!("cargo::rustc-cdylib-link-arg=VhfUm.lib");
Comment on lines +1279 to +1283
}
}
}

Expand Down Expand Up @@ -1826,18 +1889,22 @@ mod tests {
#[cfg(assert_matches_stabilized)]
assert_matches!(config.driver_config, DriverConfig::Wdm);
assert_eq!(config.cpu_architecture, CpuArchitecture::Amd64);
assert!(config.enabled_api_subsets.is_empty());
}

#[test]
fn wdm_config() {
let config = with_env(&[("CARGO_CFG_TARGET_ARCH", Some("x86_64"))], || Config {
driver_config: DriverConfig::Wdm,
enabled_api_subsets: vec![ApiSubset::Hid],
..Config::default()
});

#[cfg(assert_matches_stabilized)]
assert_matches!(config.driver_config, DriverConfig::Wdm);
assert_eq!(config.cpu_architecture, CpuArchitecture::Amd64);
assert!(config.enabled_api_subsets.contains(&ApiSubset::Hid));
assert!(!config.enabled_api_subsets.contains(&ApiSubset::Gpio));
}

#[test]
Expand Down Expand Up @@ -1867,6 +1934,7 @@ mod tests {
target_kmdf_version_minor: 15,
minimum_kmdf_version_minor: None,
}),
enabled_api_subsets: vec![ApiSubset::Hid, ApiSubset::Gpio],
..Config::default()
});

Expand All @@ -1880,6 +1948,8 @@ mod tests {
})
);
assert_eq!(config.cpu_architecture, CpuArchitecture::Amd64);
assert!(config.enabled_api_subsets.contains(&ApiSubset::Hid));
assert!(config.enabled_api_subsets.contains(&ApiSubset::Gpio));
}

#[test]
Expand Down Expand Up @@ -1909,6 +1979,7 @@ mod tests {
target_umdf_version_minor: 15,
minimum_umdf_version_minor: None,
}),
enabled_api_subsets: vec![ApiSubset::Usb],
..Config::default()
});

Expand All @@ -1922,6 +1993,8 @@ mod tests {
})
);
assert_eq!(config.cpu_architecture, CpuArchitecture::Arm64);
assert!(!config.enabled_api_subsets.contains(&ApiSubset::Hid));
assert!(config.enabled_api_subsets.contains(&ApiSubset::Usb));
}

#[test]
Expand Down
Loading