Debugging Macros

Macro bugs show up as confusing compiler errors at expansion sites. cargo expand, eprintln! in proc macros, and trybuild tests are the main debugging tools.

Recipe

cargo install cargo-expand
cargo expand -p mycrate path::to::function
RUSTFLAGS="-Z unstable-options" cargo expand --theme=monokai  # optional

// inside proc macro during dev:
eprintln!("parsed: {:?}", input);

When to reach for this: Any time expanded code does not match mental model or errors reference wrong spans.

Working Example

# Expand derive output
cargo expand -p api handlers::create_order
 
# Expand specific module
cargo expand -p my_macros derive_validate
 
# Pretty print in test with macrotest

// proc-macro crate dev
#[proc_macro_derive(MyTrait)]
pub fn derive_my_trait(input: TokenStream) -> TokenStream {
    let ast = syn::parse_macro_input!(input as DeriveInput);
    if std::env::var("DEBUG_MACRO").is_ok() {
        eprintln!("{:#?}", ast);
    }
    // ...
    TokenStream::new()
}

What this demonstrates:

• cargo expand shows post-macro Rust
• eprintln! in proc macro runs at compile time
• DEBUG_MACRO env gate avoids noisy normal builds
• Compare expansion across toolchain versions

Deep Dive

Error Quality

return syn::Error::new_spanned(&field.ident, "field must have #[validate]")
    .to_compile_error()
    .into();

• Good spans beat good messages at wrong line
• compile_error! in macro_rules! fallback arm

trybuild

#[test]
fn ui() {
    let t = trybuild::TestCases::new();
    t.compile_fail("tests/ui/missing_field.rs");
}

Gotchas

• Reading error without expand - wasted time. Fix: expand first habit.
• eprintln in published macro - noisy for users. Fix: feature flag debug-macros.
• Wrong -p package - empty expand. Fix: workspace cargo expand -p proc_crate.
• Huge expansion unreadable - hard to diff. Fix: rustfmt expanded output; snapshot with macrotest.
• Nightly-only expand features - CI on stable. Fix: document nightly optional tricks.

Alternatives

FAQs

Related

• macro_rules! - declarative macros
• syn & quote - AST debugging
• Useful Cargo Subcommands - expand install
• Macros Best Practices

Stack versions: This page was written for Rust 1.97.0 (edition 2024), Tokio 1.x, Axum 0.8, serde 1.0, sqlx 0.8, clap 4, and Polars 0.46+.