FerrousPath

Level 3 · Systems· Lesson 6 of 11 · 30 min

Procedural macros

Derive, attribute and function-like macros — Rust programs that run inside the compiler and write Rust.

Three kinds

Kind Looks like Input Output
Derive #[derive(Serialize)] the struct/enum added next to it
Attribute #[tokio::main], #[test] attribute args + the item replaces the item
Function-like sqlx::query!("…") arbitrary tokens replaces the invocation

Each is a Rust function TokenStream -> TokenStream that the compiler calls during expansion. It can run any code: parse the input, read files, even talk to a database (as sqlx does to type-check SQL). That power is why they must be used with restraint — they cost compile time and can hide a lot.

Project layout

builder/
├── Cargo.toml             # workspace
├── builder-derive/        # the proc-macro crate
│   ├── Cargo.toml
│   └── src/lib.rs
└── app/                   # a crate that uses it
# builder-derive/Cargo.toml
[lib]
proc-macro = true

[dependencies]
syn = { version = "2", features = ["full"] }
quote = "1"
proc-macro2 = "1"

A derive macro, step by step

Goal: #[derive(Builder)] on a struct generates a FooBuilder with one setter per field and a build() that reports the first missing field.

// builder-derive/src/lib.rs
use proc_macro::TokenStream;
use quote::{format_ident, quote};
use syn::{parse_macro_input, Data, DeriveInput, Fields};

#[proc_macro_derive(Builder)]
pub fn derive_builder(input: TokenStream) -> TokenStream {
    // 1. Parse the tokens into a syntax tree.
    let input = parse_macro_input!(input as DeriveInput);
    let name = &input.ident;
    let builder = format_ident!("{}Builder", name);

    // 2. Extract what we need — and reject what we do not support with a good error.
    let Data::Struct(data) = &input.data else {
        return syn::Error::new_spanned(name, "Builder can only be derived for structs")
            .to_compile_error()
            .into();
    };
    let Fields::Named(fields) = &data.fields else {
        return syn::Error::new_spanned(name, "Builder requires named fields")
            .to_compile_error()
            .into();
    };

    let idents: Vec<_> = fields.named.iter().map(|f| f.ident.as_ref().unwrap()).collect();
    let types: Vec<_> = fields.named.iter().map(|f| &f.ty).collect();
    let missing: Vec<_> = idents.iter().map(|i| format!("missing field `{i}`")).collect();

    // 3. Generate code. `#var` interpolates; `#( … )*` repeats.
    let expanded = quote! {
        #[derive(Default)]
        pub struct #builder {
            #( #idents: ::core::option::Option<#types>, )*
        }

        impl #builder {
            #(
                pub fn #idents(mut self, value: #types) -> Self {
                    self.#idents = ::core::option::Option::Some(value);
                    self
                }
            )*

            pub fn build(self) -> ::core::result::Result<#name, &'static str> {
                ::core::result::Result::Ok(#name {
                    #( #idents: self.#idents.ok_or(#missing)?, )*
                })
            }
        }

        impl #name {
            pub fn builder() -> #builder {
                #builder::default()
            }
        }
    };
    expanded.into()
}

Using it:

// app/src/main.rs
use builder_derive::Builder;

#[derive(Debug, Builder)]
struct Request {
    url: String,
    retries: u32,
}

fn main() {
    let ok = Request::builder().url("https://example.com".into()).retries(3).build();
    let bad = Request::builder().retries(3).build();
    println!("{ok:?}\n{bad:?}"); // Ok(Request { … }) / Err("missing field `url`")
}

Things that matter in practice

Spans and errors. Every token carries a span — its source location. Report problems with syn::Error::new_spanned(tokens, msg) so the error underlines the user’s code, not the macro. Never panic! for user mistakes.

Hygiene. Proc macros are unhygienic by default: generated identifiers resolve at the call site. Use absolute paths (::core::option::Option), because the user may have shadowed Option or Result, and prefer ::core over ::std so the macro works in no_std crates.

Generics. A real derive must carry the struct’s generics through:

// inside a derive, with `input: DeriveInput` and `name = &input.ident`
let (impl_generics, ty_generics, where_clause) = input.generics.split_for_impl();
let expanded = quote! {
    impl #impl_generics MyTrait for #name #ty_generics #where_clause {
        // …
    }
};

Helper attributes. #[proc_macro_derive(Builder, attributes(builder))] allows #[builder(default)] on fields; read them from field.attrs.

Testing. Put the logic in a function over proc_macro2::TokenStream so it can be unit-tested. Use cargo expand to read the output and the trybuild crate to assert on compile errors.

Compile time. syn with full features is a heavy dependency, and every invocation runs your code. A macro_rules! macro or a generic function, when sufficient, is cheaper for everyone downstream.

Attribute macros

// in the proc-macro crate
use proc_macro::TokenStream;
use quote::quote;
use syn::{parse_macro_input, ItemFn};

/// Wraps a function so it prints how long each call took.
#[proc_macro_attribute]
pub fn timed(_args: TokenStream, item: TokenStream) -> TokenStream {
    let ItemFn { attrs, vis, sig, block } = parse_macro_input!(item as ItemFn);
    let name = sig.ident.to_string();
    quote! {
        #(#attrs)* #vis #sig {
            let __start = ::std::time::Instant::now();
            let __result = (move || #block)();
            eprintln!("{} took {:?}", #name, __start.elapsed());
            __result
        }
    }
    .into()
}

This is the shape of #[tokio::main], #[test], and the route attributes in web frameworks: take an item, emit a transformed item.

Exercises

  1. Build the Builder derive in a workspace and run it. Use cargo expand to read what it generates.
  2. Make Option<T> fields optional in the builder (they default to None and the setter takes T). You will need to inspect syn::Type::Path.
  3. Support generic structs with split_for_impl.
  4. Add a #[builder(default = "expr")] field attribute.
  5. Write a trybuild test asserting that deriving Builder on an enum produces your error message.

Check your understanding

Pick an answer to see the explanation.

  1. 1.Why must procedural macros live in their own crate with proc-macro = true?

  2. 2.What can a derive macro do to the item it is attached to?

  3. 3.Which crates are the standard toolkit for writing proc macros?

Key terms in this lesson

Finished the lesson and the exercises?