pdb-bindgen 0.1.0

Generate compact no_std Rust bindings from Microsoft PDB debug data.
Documentation
#![no_std]

//! `pdb-bindgen` is the `no_std` facade for bindings generated from Microsoft PDBs.
//!
//! Depend on this crate normally for the [`pdb`] proc macro. Enable `codegen` only
//! for the build dependency, where [`Builder::generate`] discovers active source
//! markers, acquires configured PDBs, and writes the fragments the macro consumes.
//! The proc macro does not scan PDBs or source and does not write files.
//!
//! # Safety
//!
//! Generated addresses are the source-side base provider result plus a PDB RVA.
//! The provider must return the base of the currently loaded image that exactly
//! matches its configured PDB identity and must remain valid during the operation.
//! Loaded-image identity is not validated at runtime. A generated safe wrapper is
//! sound only for a source `safe fn` whose foreign contract is safe for all declared
//! inputs under those invariants; unsafe declarations retain caller obligations.
//! Global accessors return raw pointers, and callers are responsible for validity,
//! aliasing, lifetime, and mutability when dereferencing them.

#![cfg_attr(
    feature = "codegen",
    doc = r#"
# Build-script generation

Configure each image in `build.rs` with an exact logical PDB filename, GUID, and
age, then call [`Builder::generate`]. Runtime base providers belong only to the
source-side `#[pdb(image = "kernel", base = crate::kernel_base)]` declaration.

```rust,no_run
use pdb_bindgen::{Builder, Image, PdbGuid, PdbIdentity};

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let guid: PdbGuid = "12345678-9abc-def0-1234-56789abcdef0".parse()?;
    let identity = PdbIdentity::new("ntkrnlmp.pdb", guid, 1)?;
    let image = Image::new("kernel", identity)?.local_pdb("symbols/ntkrnlmp.pdb")?;

    let mut builder = Builder::new();
    builder.offline(true).disable_symbol_server();
    builder.image(image)?;
    builder.generate()?;
    Ok(())
}
```

`generate` reads Cargo's package and output directories, evaluates active `cfg` and
`cfg_attr` declarations, acquires only their referenced images, and publishes
rendered fragments deterministically. Relative local-PDB and cache paths are package
relative; the default cache is `OUT_DIR/pdb-bindgen/cache`. Offline mode forbids
network access, and `disable_symbol_server` disables server acquisition.

# Source marker shape

The marker requires generated fragments, so this is not a compiled example. Use an
inline image module.

```text
#[pdb_bindgen::pdb(image = "kernel", base = crate::kernel_base)]
mod kernel {
    #[pdb_bindgen::pdb(type_name = "EPROCESS")]
    pub struct Process {
        #[pdb_bindgen::pdb(field_name = "UniqueProcessId")]
        pub pid: usize,
    }

    #[pdb_bindgen::pdb(symbols)]
    unsafe extern "system" {
        pub safe fn PsGetCurrentProcessId() -> usize;
        pub static mut PsInitialSystemProcess: *mut Process;
    }
}
```
"#
)]

#[doc(inline)]
pub use pdb_bindgen_macro::pdb;

#[cfg(feature = "codegen")]
#[doc(inline)]
pub use pdb_bindgen_codegen::{
    Builder, CachePolicy, ConfigError, GenerateError, GenerateErrorKind, GuidErrorKind, Image,
    ParsePdbGuidError, PdbFilenameErrorKind, PdbGuid, PdbIdentity, SymbolServer,
    SymbolServerErrorKind,
};