samba-pidl — Rust rewrite of the Samba PIDL compiler

samba-pidl is a Rust reimplementation of the Perl IDL compiler (pidl) used by the Samba project. It reads Interface Definition Language (IDL) files in a format compatible with Microsoft's MIDL compiler and generates C source code, NDR wire-protocol parsers, Wireshark dissectors, Python bindings, and Rust type definitions.

The goal is a drop-in replacement for the Perl pidl script with byte-identical output on the full Samba IDL corpus (librpc/idl/*.idl), better error messages, and a clean, testable architecture.

Workspace layout

samba-pidl-rust/
├── pidl/ Library crate — all pipeline logic (lexer, parser, backends)
├── samba-pidl/ Binary crate — CLI entry point, wires pipeline stages together
├── samba-ndr/ Runtime support crate for the Rust backend (NDR traits, primitives)
├── ndr-loading/ C ABI crate — dynamic module loader API (ndr_loading.h)
├── ndrdump/ Binary — decode and pretty-print NDR blobs (port of Samba's ndrdump)
├── pidl-fuzz/ Structured fuzzer for the pidl pipeline and NDR dynamic modules
├── idl/ Vendored copy of all 95 Samba IDL files (librpc/idl/)
├── examples/ Self-contained IDL examples covering every language feature
└── docs/ Design documents (architecture, AST, parser, backends, plan)

Compilation pipeline

.idl file
 │
 ▼ preprocessor.rs — invoke cpp, parse GCC line markers
 ▼ lexer.rs — tokenise preprocessed text, track source locations
 ▼ parser/ — hand-written recursive-descent IDL parser → IdlTree
 ▼ typelist.rs — register all named types into TypeRegistry
 ▼ odl.rs — ODL-to-IDL transformation (object interfaces)
 ▼ ndr/ — NDR semantic analysis → NdrTree (levels, alignment, deferred flags)
 ▼ backend/* — one or more code-generation backends

Backends

All complete backends produce byte-identical output to the Perl reference tool on the full 95-file Samba IDL corpus.

Building

Requires Rust 1.74 or later and a C preprocessor (cpp) on PATH.

cargo build --release

The samba-pidl binary will be at target/release/samba-pidl.

Running

# Generate NDR parser C source for an IDL file
samba-pidl --outputdir=out --ndr-parser librpc/idl/samr.idl
# Generate C header
samba-pidl --outputdir=out --header librpc/idl/samr.idl
# Generate Wireshark dissector
samba-pidl --outputdir=out --ws-parser librpc/idl/samr.idl
# Generate Rust types (against the samba-ndr runtime crate)
samba-pidl --outputdir=out --rust librpc/idl/samr.idl
# Add include directories for IDL files that #include others
samba-pidl --includedir librpc/idl --ndr-parser librpc/idl/netlogon.idl

Testing

# Run all workspace tests
cargo test --workspace
# Run only the pidl library tests (178+ unit tests + integration tests)
cargo test -p pidl
# Run ndrdump blackbox tests (14 tests decoding PAC, SAMR, NBT, NETLOGON blobs)
cargo test -p ndrdump

Fuzzing

pidl-fuzz exercises both the IDL parser pipeline and compiled NDR modules. See pidl-fuzz/README.md for the full guide.

# Deterministic: 65 curated IDL inputs
cargo run --release -p pidl-fuzz
# Random: 5 000 seeded-PRNG IDL cases
cargo run --release -p pidl-fuzz -- --count 5000 random
# Module: fuzz a compiled .so (decode → encode → free cycle)
cargo run --release -p pidl-fuzz -- --count 5000 module target/release/libndr_krb5pac.so

CI

A local CI runner mirrors the GitHub Actions pipeline:

./contrib/ci/local-ci.sh all # run all jobs: fmt, clippy, build, doc, test, examples
./contrib/ci/local-ci.sh build test # run specific jobs
./contrib/ci/local-ci.sh --list # list available jobs

Jobs run in dependency order (clippy/doc/test/examples each require a passing build). Job timing and a pass/fail summary table are printed at the end.

The examples job compiles every file in examples/ with --header, --ndr-parser, and --dump-idl, and additionally runs --client and --server on examples/full-protocol.idl.

ndrdump

ndrdump decodes NDR-encoded RPC binary blobs and prints a human-readable representation, equivalent to Samba's C ndrdump tool. It uses types generated by the Rust backend from the vendored IDL files.

cargo run --bin ndrdump -- krb5pac PAC_DATA pull test.pac

samba-ndr runtime crate

The samba-ndr crate provides the traits and primitives required by Rust-backend-generated code:

• NdrEncode / NdrDecode — serialisation traits
• NdrPrint — human-readable dump trait (used by ndrdump)
• NdrBuffer — read/write cursor over a byte slice
• Primitive implementations (u8, u16, u32, u64, i*, bool)
• Samba-specific types: Guid, PolicyHandle, DomSid, VecSized

Documentation

Relationship to Samba

This project is developed alongside the Samba source tree. The Perl pidl in samba/pidl/ remains the authoritative reference during development: every backend is verified by running both tools on the same IDL input and diffing the output. Once all backends pass the regression suite, samba-pidl could be integrated into the Samba build system as a drop-in replacement.

License

GPL-3.0-or-later — same as Samba.