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
- Build the
Builderderive in a workspace and run it. Usecargo expandto read what it generates. - Make
Option<T>fields optional in the builder (they default toNoneand the setter takesT). You will need to inspectsyn::Type::Path. - Support generic structs with
split_for_impl. - Add a
#[builder(default = "expr")]field attribute. - Write a
trybuildtest asserting that derivingBuilderon an enum produces your error message.
Check your understanding
Pick an answer to see the explanation.
1.Why must procedural macros live in their own crate with
proc-macro = true?2.What can a derive macro do to the item it is attached to?
3.Which crates are the standard toolkit for writing proc macros?