Expand description
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.
§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.
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.
#[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;
}
}Structs§
- Builder
- Collects image configuration and builder-wide PDB acquisition policy.
- Cache
Policy - Describes where PDB acquisition keeps cached files.
- Generate
Error - An error from
Builder::generate. - Image
- A logical image and its authoritative PDB configuration.
- Parse
PdbGuid Error - An error returned when canonical PDB GUID text is malformed.
- PdbGuid
- A PDB GUID represented by its conventional GUID fields.
- PdbIdentity
- An explicit Symbol Server PDB identity.
- Symbol
Server - Describes the configured Symbol Server source.
Enums§
- Config
Error - Describes a configuration validation failure.
- Generate
Error Kind - The category of a
GenerateError. - Guid
Error Kind - Describes why canonical PDB GUID text could not be parsed.
- PdbFilename
Error Kind - Describes why a logical PDB filename is invalid.
- Symbol
Server Error Kind - Describes why a Symbol Server URL is invalid.
Attribute Macros§
- pdb
- Replaces a named struct marker with its generated item fragment.