pdb-bindgen 0.1.0

Generate compact no_std Rust bindings from Microsoft PDB debug data.
Documentation

pdb-bindgen selects Rust-facing declarations in source, validates them at build time against explicitly configured Microsoft PDBs, and emits compact no_std bindings into OUT_DIR.

[!IMPORTANT] The target dependency contains only the facade and proc macro. PDB parsing, filesystem access, caching, and networking stay in the build dependency.


✨ What it does

  • Focused bindings. Select named structs, unions, fields, free functions, and typed globals instead of reflecting an entire C++ program.
  • Proven layouts. Generate natural and packed MSVC records only when the PDB facts uniquely prove their layout, including supported bitfields.
  • Editor-friendly output. Logical bitfields become ordinary inherent getter and setter methods that rust-analyzer can discover after generation.
  • Clean rebuilds. Deterministic fragments and manifests are not rewritten when their bytes have not changed.
  • Fail-closed behavior. Missing, unsupported, or ambiguous facts stop generation instead of producing guessed bindings.

[!TIP] Use a local PDB for reproducible offline builds, or let the build dependency use its cache and Microsoft Symbol Server acquisition.

🚀 Quick start

Use the facade as a normal target dependency and again as a build dependency with code generation enabled:

[!NOTE] The normal dependency stays no_std. Enable codegen only for the build dependency.

[dependencies]
pdb-bindgen = { version = "0.1", default-features = false }

[build-dependencies]
pdb-bindgen = { version = "0.1", default-features = false, features = ["codegen"] }

Configure the exact PDB identity and a local PDB in build.rs:

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(())
}

Mark an inline image module in the consumer crate. The image key and base provider are source-side facts; replace the PDB metadata, path, and base provider with your own.

#[inline]
fn kernel_base() -> usize { /* loaded image base */ }

#[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,
        // A PDB bitfield becomes flags() and set_flags(...) methods.
        #[pdb_bindgen::pdb(field_name = "Flags")]
        pub flags: u32,
    }

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

[!TIP] Put the image marker on an inline module. The declaration shape is consumed by build-time generation, so the example is shown as source rather than a standalone doctest. #[inline] on the base provider is an optimization hint, not a correctness requirement.

🧩 Generated API

  • Normal fields remain Rust fields with compile-time size, alignment, and offset checks.
  • Bitfields become field() and set_field(...) methods over hidden backing storage. A read_only bitfield receives only the getter.
  • Functions dispatch through the source-provided image base plus the PDB RVA.
  • Globals become accessors returning raw pointers to the global storage.

Generated fragments live in OUT_DIR; no generated bindings are checked into source.

🔬 What reaches the CPU

The generated bindings are ordinary Rust. A representative function with PDB RVA 0x1234, compiled using Rust 1.97.1 with -O for x86_64-pc-windows-msvc, produces this body after omitting COFF and unwind directives:

subq    $40, %rsp
callq   loaded_kernel_base
addq    $4660, %rax
addq    $40, %rsp
rex64 jmpq    *%rax

There is no linker import for the PDB function. The wrapper obtains the loaded image base, adds the compile-time RVA, and dispatches directly to the resulting address.

A selected normal field remains a normal field. For a representative usize field at PDB offset 0x20, this consumer helper:

pub extern "C" fn read_pid(process: &kernel::Process) -> usize {
    process.pid
}

compiles to one load:

movq    32(%rcx), %rax
retq

[!NOTE] Exact instruction spelling and prologues may change between compiler versions. The stable property is the shape: a constant-RVA indirect call and ordinary field access, with no runtime PDB parser in either path.

⚠️ Platform and safety

The supported ABI surface is AMD64 Microsoft PDBs and the Windows x86_64 extern "system" calling convention.

[!WARNING] A PDB describes an image; it does not prove which image is currently loaded. The base provider must return the base of the image matching the configured PDB identity and keep it valid for the operation. pdb-bindgen does not validate that identity at runtime.

Use safe fn only for a genuinely safe foreign contract under those image and base invariants. Global accessors return raw pointers; dereferencing them remains the caller's responsibility for validity, aliasing, lifetime, and mutability.

🎯 Deliberate limits

[!NOTE] pdb-bindgen is deliberately a precise binding generator, not broad C++ reflection.

It does not recover inheritance, vtables, member functions, TLS, imports or exports, or fuzzy/decorated symbol matches. Non-Windows and non-x86_64 runtime targets are outside the supported contract.

For the full API, diagnostics, and configuration surface, see the crate documentation.

📄 License

MIT © 2026 SilentBless. See the license.