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. Enablecodegenonly for the build dependency.
[]
= { = "0.1", = false }
[]
= { = "0.1", = false, = ["codegen"] }
Configure the exact PDB identity and a local PDB in build.rs:
use ;
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.
[!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()andset_field(...)methods over hidden backing storage. Aread_onlybitfield 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"
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-bindgendoes 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-bindgenis 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.