pdb-bindgen-codegen 0.1.0

Build-time discovery, PDB acquisition, and binding generation for pdb-bindgen.
Documentation
use super::ConfigError;
use crate::PdbIdentity;
use std::path::{Path, PathBuf};

/// A logical image and its authoritative PDB configuration.
///
/// The runtime base provider belongs to the source-side
/// `#[pdb(image = "...", base = path)]` declaration. Build configuration deliberately
/// does not duplicate that provider.
#[derive(Clone, Debug, Eq, PartialEq)]
pub struct Image {
    key: String,
    identity: PdbIdentity,
    local_pdb: Option<PathBuf>,
}

impl Image {
    /// Creates an image configuration.
    ///
    /// `key` is matched exactly against source-visible `#[pdb(image = "...")]`
    /// values during generation. No normalization is performed.
    ///
    /// # Errors
    ///
    /// Returns [`ConfigError::EmptyImageKey`] for an empty key.
    pub fn new(key: impl Into<String>, identity: PdbIdentity) -> Result<Self, ConfigError> {
        let key = key.into();
        if key.is_empty() {
            return Err(ConfigError::EmptyImageKey);
        }
        Ok(Self {
            key,
            identity,
            local_pdb: None,
        })
    }

    /// Supplies a physical local PDB path for this image.
    ///
    /// The path is retained without filesystem access. Generation may use it before
    /// cache or server lookup.
    ///
    /// # Errors
    ///
    /// Returns [`ConfigError::EmptyLocalPdbPath`] when `path` is empty.
    pub fn local_pdb(mut self, path: impl AsRef<Path>) -> Result<Self, ConfigError> {
        let path = path.as_ref();
        if path.as_os_str().is_empty() {
            return Err(ConfigError::EmptyLocalPdbPath);
        }
        self.local_pdb = Some(path.to_path_buf());
        Ok(self)
    }

    /// Returns the exact source-visible image key.
    #[must_use]
    pub fn key(&self) -> &str {
        &self.key
    }

    /// Returns the authoritative PDB identity.
    #[must_use]
    pub const fn identity(&self) -> &PdbIdentity {
        &self.identity
    }

    /// Returns the directly supplied local PDB path, if any.
    #[must_use]
    pub fn local_pdb_path(&self) -> Option<&Path> {
        self.local_pdb.as_deref()
    }

    pub(super) fn resolve_local_pdb(&mut self, package: &Path) {
        if let Some(path) = self.local_pdb.as_mut().filter(|path| path.is_relative()) {
            *path = package.join(&*path);
        }
    }
}

#[cfg(test)]
mod tests {
    use super::*;

    const GUID_TEXT: &str = "12345678-9abc-def0-1234-56789abcdef0";

    fn identity(filename: &str) -> PdbIdentity {
        PdbIdentity::new(filename, GUID_TEXT.parse().expect("valid GUID"), 0)
            .expect("valid identity")
    }

    fn image(key: &str) -> Image {
        Image::new(key, identity("kernel.pdb")).expect("valid image")
    }

    #[test]
    fn image_validates_key_and_local_path() {
        let configured = Image::new("ntoskrnl", identity("ntkrnlmp.pdb"))
            .expect("valid image")
            .local_pdb("symbols/ntkrnlmp.pdb")
            .expect("nonempty local path");

        assert_eq!(configured.key(), "ntoskrnl");
        assert_eq!(configured.identity().filename(), "ntkrnlmp.pdb");
        assert_eq!(
            configured.local_pdb_path(),
            Some(Path::new("symbols/ntkrnlmp.pdb"))
        );
        assert_eq!(
            Image::new("", identity("x")),
            Err(ConfigError::EmptyImageKey)
        );
        assert_eq!(
            image("key").local_pdb(""),
            Err(ConfigError::EmptyLocalPdbPath)
        );
    }
}