feat: enhance debug tracing in bindgen and config modules

crates/wdk-build/src/bindgen.rs

@@ -1,7 +1,7 @@
 // Copyright (c) Microsoft Corporation
 // License: MIT OR Apache-2.0
 
-use std::borrow::Borrow;
+use std::{borrow::Borrow, fmt};
 
 use bindgen::{
     callbacks::{ItemInfo, ItemKind, ParseCallbacks},
@@ -22,7 +22,7 @@ pub trait BuilderExt {
     ///
     /// Implementation may return `wdk_build::ConfigError` if it fails to create
     /// a builder
-    fn wdk_default(config: impl Borrow<Config>) -> Result<Builder, ConfigError>;
+    fn wdk_default(config: impl Borrow<Config> + fmt::Debug) -> Result<Builder, ConfigError>;
 }
 
 #[derive(Debug)]
@@ -64,7 +64,8 @@ impl BuilderExt for Builder {
     ///
     /// Will return `wdk_build::ConfigError` if any of the resolved include or
     /// library paths do not exist
-    fn wdk_default(config: impl Borrow<Config>) -> Result<Self, ConfigError> {
+    #[tracing::instrument(level = "debug")]
+    fn wdk_default(config: impl Borrow<Config> + fmt::Debug) -> Result<Self, ConfigError> {
         let config = config.borrow();
 
         let mut builder = Self::default()
@@ -175,6 +176,7 @@ impl ParseCallbacks for WdkCallbacks {
 }
 
 impl WdkCallbacks {
+    #[tracing::instrument(level = "trace")]
     fn new(config: &Config) -> Self {
         Self {
             wdf_function_table_symbol_name: config.compute_wdffunctions_symbol_name(),
@@ -196,6 +198,7 @@ impl WdkCallbacks {
 // Returns `ConfigError::MsrvNotSupportedByBindgen` if the MSRV is not supported
 // by bindgen, or `ConfigError::SemverError` if the MSRV cannot be parsed as a
 // semver version.
+#[tracing::instrument(level = "trace")]
 fn get_rust_target() -> Result<bindgen::RustTarget, ConfigError> {
     let nightly_feature = cfg!(feature = "nightly");
     let nightly_toolchain = rustversion::cfg!(nightly);
@@ -223,6 +226,7 @@ fn get_rust_target() -> Result<bindgen::RustTarget, ConfigError> {
 // Retrieves the stable Rust target for the current build configuration.
 // Queries the MSRV from the `CARGO_PKG_RUST_VERSION` environment variable and
 // uses it to create a `bindgen::RustTarget::stable` value.
+#[tracing::instrument(level = "trace")]
 fn get_stable_rust_target() -> Result<bindgen::RustTarget, ConfigError> {
     let package_msrv = semver::Version::parse(env!("CARGO_PKG_RUST_VERSION"))
         .map_err(|e| ConfigError::RustVersionParseError { error_source: e })?;
@@ -243,7 +247,7 @@ fn get_stable_rust_target() -> Result<bindgen::RustTarget, ConfigError> {
 // Returns `ConfigError::CargoMetadataPackageNotFound` if the `wdk-build`
 // package is not found, or `ConfigError::UnsupportedRustEdition` if the edition
 // is not supported.
-#[tracing::instrument(level = "debug")]
+#[tracing::instrument(level = "trace")]
 fn get_rust_edition() -> Result<bindgen::RustEdition, ConfigError> {
     const WDK_BUILD_PACKAGE_NAME: &str = "wdk-build";
     // Run `cargo_metadata` in the same working directory as the top level manifest

crates/wdk-build/src/lib.rs

@@ -340,6 +340,7 @@ impl Default for Config {
 impl Config {
     /// Create a new [`Config`] with default values
     #[must_use]
+    #[tracing::instrument(level = "debug")]
     pub fn new() -> Self {
         Self::default()
     }
@@ -409,6 +410,7 @@ impl Config {
     /// was already configured via [`configure_wdk_binary_build`],
     /// [`configure_wdk_library_build`], or
     /// [`configure_wdk_library_build_and_then`]
+    #[tracing::instrument(level = "debug")]
     pub fn emit_check_cfg_settings() {
         for (cfg_key, allowed_values) in EXPORTED_CFG_SETTINGS.iter() {
             let allowed_cfg_value_string =
@@ -442,6 +444,7 @@ impl Config {
     /// Expose `cfg` settings based on this [`Config`] to enable conditional
     /// compilation. This emits specially formatted prints to Cargo based on
     /// this [`Config`].
+    #[tracing::instrument(level = "trace")]
     fn emit_cfg_settings(&self) -> Result<(), ConfigError> {
         Self::emit_check_cfg_settings();
 
@@ -476,6 +479,7 @@ impl Config {
     ///
     /// This function will return an error if any of the required paths do not
     /// exist.
+    #[tracing::instrument(level = "debug")]
     pub fn include_paths(&self) -> Result<impl Iterator<Item = PathBuf>, ConfigError> {
         let mut include_paths = vec![];
         let sdk_version = detect_windows_sdk_version(&self.wdk_content_root)?;
@@ -565,6 +569,7 @@ impl Config {
     ///
     /// This function will return an error if any of the required paths do not
     /// exist.
+    #[tracing::instrument(level = "debug")]
     pub fn library_paths(&self) -> Result<impl Iterator<Item = PathBuf>, ConfigError> {
         let mut library_paths = vec![];
         let sdk_version = detect_windows_sdk_version(&self.wdk_content_root)?;
@@ -617,6 +622,7 @@ impl Config {
 
     /// Return an iterator of strings that represent compiler definitions
     /// derived from the `Config`
+    #[tracing::instrument(level = "debug")]
     pub fn preprocessor_definitions(&self) -> impl Iterator<Item = (String, Option<String>)> {
         // _WIN32_WINNT=$(WIN32_WINNT_VERSION);
         // WINVER=$(WINVER_VERSION);
@@ -712,6 +718,7 @@ impl Config {
 
     /// Return an iterator of strings that represent compiler flags (i.e.
     /// warnings, settings, etc.) used by bindgen to parse WDK headers
+    #[tracing::instrument(level = "debug")]
     pub fn wdk_bindgen_compiler_flags() -> impl Iterator<Item = String> {
         vec![
             // Enable Microsoft C/C++ extensions and compatibility options (https://clang.llvm.org/docs/UsersManual.html#microsoft-extensions)
@@ -752,6 +759,7 @@ impl Config {
     /// # Errors
     /// [`ConfigError`] - if the headers for the given [`ApiSubset`] could not
     /// be determined
+    #[tracing::instrument(level = "debug")]
     pub fn headers(
         &self,
         api_subset: ApiSubset,
@@ -773,6 +781,7 @@ impl Config {
             .into_iter())
     }
 
+    #[tracing::instrument(level = "trace")]
     fn base_headers(&self) -> Vec<&'static str> {
         match &self.driver_config {
             DriverConfig::Wdm | DriverConfig::Kmdf(_) => {
@@ -784,6 +793,7 @@ impl Config {
         }
     }
 
+    #[tracing::instrument(level = "trace")]
     fn wdf_headers(&self) -> Vec<&'static str> {
         if matches!(
             self.driver_config,
@@ -795,6 +805,7 @@ impl Config {
         }
     }
 
+    #[tracing::instrument(level = "trace")]
     fn gpio_headers(&self) -> Vec<&'static str> {
         let mut headers = vec!["gpio.h"];
         if matches!(self.driver_config, DriverConfig::Kmdf(_)) {
@@ -803,6 +814,7 @@ impl Config {
         headers
     }
 
+    #[tracing::instrument(level = "trace")]
     fn hid_headers(&self) -> Vec<&'static str> {
         let mut headers = vec!["hidclass.h", "hidsdi.h", "hidpi.h", "vhf.h"];
         if matches!(
@@ -818,6 +830,7 @@ impl Config {
         headers
     }
 
+    #[tracing::instrument(level = "trace")]
     fn parallel_ports_headers(&self) -> Vec<&'static str> {
         let mut headers = vec!["ntddpar.h", "ntddser.h"];
         if matches!(
@@ -829,6 +842,7 @@ impl Config {
         headers
     }
 
+    #[tracing::instrument(level = "trace")]
     fn spb_headers(&self) -> Vec<&'static str> {
         let mut headers = vec!["spb.h", "reshub.h"];
         if matches!(
@@ -843,6 +857,7 @@ impl Config {
         headers
     }
 
+    #[tracing::instrument(level = "trace")]
     fn storage_headers(&self) -> Vec<&'static str> {
         let mut headers = vec![
             "ehstorioctl.h",
@@ -875,6 +890,7 @@ impl Config {
         headers
     }
 
+    #[tracing::instrument(level = "trace")]
     fn usb_headers(&self) -> Result<Vec<String>, ConfigError> {
         let mut headers = Vec::new();
         headers.extend(
@@ -942,6 +958,7 @@ impl Config {
     /// This function checks if the current Clang version is 20.0 or newer,
     /// where the issue was fixed. See
     /// <https://github.com/llvm/llvm-project/issues/124869> for details.
+    #[tracing::instrument(level = "trace")]
     fn should_include_ufxclient() -> bool {
         const MINIMUM_CLANG_MAJOR_VERSION_WITH_INVALID_INLINE_FIX: u32 = 20;
 
@@ -980,9 +997,10 @@ impl Config {
     /// # Errors
     /// [`ConfigError`] - if the headers for a [`ApiSubset`] could not be
     /// determined
+    #[tracing::instrument(level = "debug")]
     pub fn bindgen_header_contents(
         &self,
-        api_subsets: impl IntoIterator<Item = ApiSubset>,
+        api_subsets: impl IntoIterator<Item = ApiSubset> + fmt::Debug,
     ) -> Result<String, ConfigError> {
         Ok(api_subsets
             .into_iter()
@@ -1000,6 +1018,7 @@ impl Config {
     ///
     /// This function will return an error if the [`Config`] fails to be
     /// serialized
+    #[tracing::instrument(level = "debug")]
     pub fn configure_library_build(&self) -> Result<(), ConfigError> {
         self.emit_cfg_settings()
     }
@@ -1008,6 +1027,7 @@ impl Config {
     /// dispatching based off of the [`Config`]. Returns `None` if the driver
     /// model is [`DriverConfig::Wdm`]
     #[must_use]
+    #[tracing::instrument(level = "debug")]
     pub fn compute_wdffunctions_symbol_name(&self) -> Option<String> {
         let (wdf_major_version, wdf_minor_version) = match self.driver_config {
             DriverConfig::Kmdf(config) => {
@@ -1040,6 +1060,7 @@ impl Config {
     /// # Panics
     ///
     /// Panics if the invoked from outside a Cargo build environment
+    #[tracing::instrument(level = "debug")]
     pub fn configure_binary_build(&self) -> Result<(), ConfigError> {
         if !Self::is_crt_static_linked() {
             cfg_if::cfg_if! {
@@ -1160,6 +1181,7 @@ impl Config {
         self.emit_cfg_settings()
     }
 
+    #[tracing::instrument(level = "trace")]
     fn is_crt_static_linked() -> bool {
         const STATICALLY_LINKED_C_RUNTIME_FEATURE_NAME: &str = "crt-static";
 
@@ -1188,6 +1210,7 @@ impl Config {
     ///
     /// KMDF/AMD64: `C:\...\Lib\10.0.22621.0\km\x64`
     /// UMDF/ARM64: `C:\...\Lib\10.0.22621.0\um\arm64`
+    #[tracing::instrument(level = "trace")]
     fn sdk_library_path(&self, sdk_version: String) -> Result<PathBuf, ConfigError> {
         let windows_sdk_library_path =
             self.wdk_content_root
@@ -1211,6 +1234,7 @@ impl Config {
 
     /// Returns the path to the latest available UCX header file present in the
     /// Lib folder of the WDK content root
+    #[tracing::instrument(level = "trace")]
     fn ucx_header(&self) -> Result<String, ConfigError> {
         let sdk_version = utils::detect_windows_sdk_version(&self.wdk_content_root)?;
         let ucx_header_root_dir = self.sdk_library_path(sdk_version)?.join("ucx");
@@ -1312,6 +1336,7 @@ impl CpuArchitecture {
 /// Panics if a `Cargo.lock` file cannot be found in any of the ancestors of
 /// `OUT_DIR` or if this function was called outside of a `build.rs` file
 #[must_use]
+#[tracing::instrument(level = "debug")]
 pub fn find_top_level_cargo_manifest() -> PathBuf {
     let out_dir =
         PathBuf::from(std::env::var("OUT_DIR").expect(
@@ -1339,6 +1364,7 @@ pub fn find_top_level_cargo_manifest() -> PathBuf {
 ///
 /// This function will return an error if the [`Config`] fails to be
 /// serialized
+#[tracing::instrument(level = "debug")]
 pub fn configure_wdk_library_build() -> Result<(), ConfigError> {
     match Config::from_env_auto() {
         Ok(config) => {
@@ -1378,6 +1404,7 @@ pub fn configure_wdk_library_build() -> Result<(), ConfigError> {
 ///
 /// This function will return an error if the [`Config`] fails to be
 /// serialized
+#[tracing::instrument(level = "debug", skip(f))]
 pub fn configure_wdk_library_build_and_then<F, E>(mut f: F) -> Result<(), E>
 where
     F: FnMut(Config) -> Result<(), E>,
@@ -1386,6 +1413,7 @@ where
     match Config::from_env_auto() {
         Ok(config) => {
             config.configure_library_build()?;
+            debug!("Calling closure with {config:#?}");
             Ok(f(config)?)
         }
         Err(ConfigError::TryFromCargoMetadataError(
@@ -1417,6 +1445,7 @@ where
 /// # Panics
 ///
 /// Panics if the invoked from outside a Cargo build environment
+#[tracing::instrument(level = "debug")]
 pub fn configure_wdk_binary_build() -> Result<(), ConfigError> {
     Config::from_env_auto()?.configure_binary_build()
 }
@@ -1450,6 +1479,7 @@ static EXPORTED_CFG_SETTINGS: LazyLock<Vec<(&'static str, Vec<&'static str>)>> =
 ///
 /// Panics if the WDK version number cannot be extracted from
 /// the version string.
+#[tracing::instrument(level = "debug")]
 pub fn detect_wdk_build_number() -> Result<u32, ConfigError> {
     let wdk_content_root =
         utils::detect_wdk_content_root().ok_or(ConfigError::WdkContentRootDetectionError)?;