Skip to content
Tutorials Center
My learning

Topics

Lesson 65 of 132 ยท Modules, Packages and Macros

Procedural and Derive Macros

Understand Rust procedural macros: derive, attribute and function-like macros, what #[derive(Debug)] expands to, how serde works, and a proc-macro crate sketch.

Every Rust program you have written so far probably contains a line like #[derive(Debug, Clone, PartialEq)]. That single line writes dozens of lines of code for you, and it is not a macro_rules! macro. It is a procedural macro: a function, written in Rust, that the compiler runs at build time. It receives your source code as a stream of tokens and returns new source code.

Procedural macros ("proc macros") are the engine behind #[derive(...)], #[tokio::main], #[test]-style attributes in many crates, and serde's #[derive(Serialize, Deserialize)]. You will use them far more often than you write them. This lesson explains the three kinds, shows exactly what a derive generates (using code you can run), and sketches how a proc-macro crate is built. If you have not seen declarative macros yet, start with Declarative Macros.

The three kinds

Kind You write Looks like What it receives
Derive macro #[derive(MyTrait)] on a struct or enum #[derive(Debug)] the type definition
Attribute macro #[my_attr(args)] on an item #[tokio::main], #[route(GET, "/")] the arguments and the whole item
Function-like macro my_macro!(...) sqlx::query!("...") the tokens between the brackets

All three are functions from TokenStream to TokenStream. A derive macro can only add new items (usually an impl block) next to the type; it cannot change the type. An attribute macro receives the item and can rewrite or replace it. A function-like macro looks like macro_rules! from the outside but can run arbitrary Rust logic inside.

What a derive macro really generates

The best way to understand derive is to write by hand what it would produce. Start with the version that uses the attribute:

Rust Derive: the one-line version

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with io::stdin().read_line()), it gets the next line from this box.

Now the same four traits written out manually. This is, in spirit, what the compiler's built-in derive macros emit (the real expansion has a few extra attributes, but the logic is this):

Rust What derive expands to (hand-written)

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with io::stdin().read_line()), it gets the next line from this box.

The output is identical. Notice the pattern every derive follows: look at each field and call the trait's method on it. Clone clones every field, PartialEq compares every field, Default defaults every field. That is why a derive only works when every field's type also implements the trait.

For a generic struct such as struct Wrapper<T>, the derive adds a bound: impl<T: Clone> Clone for Wrapper<T>. That rule is simple but sometimes too strict; when it is, you write the impl by hand.

When a field blocks the derive

Rust A field without Debug (fails on purpose)

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with io::stdin().read_line()), it gets the next line from this box.

The compiler reports error E0277 with the message "Secret doesn't implement Debug", pointing at the secret: Secret field inside the derive and suggesting that you add #[derive(Debug)] to Secret. The derive generated code that calls Debug on every field, and one of those calls does not type-check. Errors from derives point at your field rather than at generated code, which is a nice courtesy of the macro system.

Sometimes you do not want a field in the output. Then you implement the trait yourself and skip it:

Rust Writing the Debug impl yourself to hide a field

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with io::stdin().read_line()), it gets the next line from this box.

Derives you will meet

The standard library gives you these derives: Debug, Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Hash and Default. Some details worth knowing:

  • Copy requires Clone as well, and every field must be Copy. A String field makes #[derive(Copy)] fail with E0204.
  • PartialOrd and Ord compare fields in declaration order, so reorder your fields carefully. For enums, variants compare by their position in the declaration.
  • Hash and Eq should agree with each other. If you derive both, they do. If you hand-write PartialEq, hand-write Hash too.
  • Default on an enum needs a #[default] attribute on one unit variant.
Rust Field order decides how Ord compares

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with io::stdin().read_line()), it gets the next line from this box.

Version sorts correctly (major first, then minor, then patch) only because the fields are declared in that order. Swap the declarations and the sorting silently changes.

Writing your own derive (read-only)

Our online editor compiles a single file without external crates, so you cannot define a proc macro here. This is what it looks like on your machine. A proc macro must live in its own crate with proc-macro = true, because the compiler loads it as a plugin.

TOML
# describe_derive/Cargo.toml   (read-only: needs Cargo and crates.io)
[package]
name = "describe_derive"
version = "0.1.0"
edition = "2024"

[lib]
proc-macro = true

[dependencies]
syn = { version = "2", features = ["full"] }
quote = "1"
proc-macro2 = "1"
Rust
// describe_derive/src/lib.rs   (read-only)
use proc_macro::TokenStream;
use quote::quote;
use syn::{parse_macro_input, Data, DeriveInput, Fields};

#[proc_macro_derive(Describe)]
pub fn derive_describe(input: TokenStream) -> TokenStream {
    // 1. Parse the tokens into a syntax tree of the struct.
    let ast = parse_macro_input!(input as DeriveInput);
    let name = &ast.ident;

    // 2. Collect the field names.
    let fields: Vec<String> = match &ast.data {
        Data::Struct(s) => match &s.fields {
            Fields::Named(named) => named
                .named
                .iter()
                .map(|f| f.ident.as_ref().unwrap().to_string())
                .collect(),
            _ => vec![],
        },
        _ => vec![],
    };

    // 3. Generate an impl block with quote!.
    let expanded = quote! {
        impl #name {
            pub fn field_names() -> &'static [&'static str] {
                &[#(#fields),*]
            }
        }
    };
    expanded.into()
}

Three crates do the heavy lifting in almost every proc macro:

  • proc_macro (in the standard distribution) provides TokenStream, the raw tokens in and out.
  • syn parses a TokenStream into a typed syntax tree (DeriveInput, ItemFn, Expr, ...). Writing the parser yourself would be painful.
  • quote turns Rust-looking templates back into tokens, with #variable interpolation and #(...)* repetition, very much like macro_rules!.

A user then adds the crate as a dependency and writes #[derive(Describe)] struct User { ... }.

A runnable stand-in with macro_rules!

You can imitate the idea of a "derive that lists the fields" inside one file with macro_rules!. It is not a real derive (you call a macro that defines the struct, instead of annotating it), but it shows the same generate-an-impl idea and runs here:

Rust Imitating a derive with macro_rules!

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with io::stdin().read_line()), it gets the next line from this box.

A real derive is more flexible because it works on a struct you wrote normally, and it can parse generics, attributes and visibility properly. The macro_rules version is a fine choice for small internal helpers.

Attribute macros

An attribute macro receives two token streams: the arguments inside the brackets, and the item it is attached to. It returns the replacement. Typical uses: wrapping a function, registering routes, generating test cases.

#[tokio::main] is the famous one. You write async fn main(), and the macro rewrites it into a normal fn main() that builds a runtime and blocks on your body. Here is a runnable, hand-expanded illustration of that kind of rewrite, a #[log_calls]-style wrapper:

Rust What an attribute macro does (hand-expanded)

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with io::stdin().read_line()), it gets the next line from this box.

The macro takes the original body, wraps it, and keeps the signature. Because the attribute sees the whole item, it can also add parameters, rename things, or generate extra functions. That power is why attribute macros need care: the code you read is not the code that runs.

Function-like proc macros

These are invoked with ! like macro_rules! macros but are programmed in Rust. They shine when the input is a mini language: sqlx::query!("SELECT ...") checks the SQL against a database at compile time, and html! { ... } templates in some web frameworks parse markup. Use a function-like proc macro when the syntax is too rich for macro_rules! patterns, or when the macro needs to compute something (parse a file, check a string).

How serde's derive works

serde is the most widely used derive in the ecosystem. Real code (read-only, needs the serde and serde_json crates):

Rust
// Cargo.toml: serde = { version = "1", features = ["derive"] }
//             serde_json = "1"
use serde::{Deserialize, Serialize};

#[derive(Serialize, Deserialize, Debug)]
struct User {
    id: u32,
    #[serde(rename = "userName")]
    name: String,
    #[serde(default)]
    admin: bool,
}

fn main() -> Result<(), serde_json::Error> {
    let json = r#"{"id": 7, "userName": "ada"}"#;
    let user: User = serde_json::from_str(json)?;
    println!("{user:?}");
    println!("{}", serde_json::to_string(&user)?);
    Ok(())
}

#[derive(Serialize)] generates an impl Serialize for User that walks the fields and tells a serializer (JSON, TOML, YAML...) "here is a struct named User with field id ... ". The attributes #[serde(rename = "...")] and #[serde(default)] are not separate macros: they are helper attributes that the derive reads while generating code. The trait and the format are separate on purpose, so adding a new file format does not require touching your structs.

The idea is easy to imitate by hand with a trait. This runnable example plays the role of Serialize and the generated impl:

Rust A hand-written Serialize-style trait

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with io::stdin().read_line()), it gets the next line from this box.

For ten structs, that boilerplate would be tedious and error-prone. A derive removes it, which is the whole value proposition of procedural macros.

Costs and cautions

  • Compile time. Proc macros run on every build. syn with the full feature is large; heavy derive use can add noticeable seconds to a build.
  • Separate crate. Every proc macro needs its own proc-macro = true crate, which complicates small projects. A workspace helps.
  • Error messages. Good macros report errors with syn::Error pointing at the exact token. Bad ones produce a wall of generated code in the message.
  • Opacity. Use cargo expand to see what a derive produced when something surprising happens.
  • Security. A proc macro is arbitrary code running at build time with your user's permissions. Treat adding one like adding any other dependency.

When to use which macro

  1. Use a plain function or generic first.
  2. Use macro_rules! for repetition and small custom syntax (Declarative Macros).
  3. Use a derive when a trait impl is mechanical and follows the type's shape.
  4. Use an attribute macro to transform an item (wrapping, registering).
  5. Use a function-like proc macro for embedded mini languages or compile-time checks.

Attributes in general, including the built-in ones like #[inline] and #[cfg], are the subject of the next lesson.

Check your understanding

Quick check ยท 5 questions

of 5 answered You scored / 5 ยท perfect!

  1. 1. What is a procedural macro?

    Proc macros are compiled Rust functions the compiler loads as plugins. They take a TokenStream and return a TokenStream.
  2. 2. Why does #[derive(Debug)] fail on a struct that has a field whose type does not implement Debug?

    A derive generates code that uses the trait on each field, so each field's type must implement the trait too (error E0277).
  3. 3. Where must a procedural macro be defined?

    The compiler loads proc macros as compiled plugins, so they must be in their own crate marked with proc-macro = true in its Cargo.toml.
  4. 4. What do the syn and quote crates do?

    syn turns a TokenStream into typed AST nodes, and quote generates a TokenStream from Rust-like templates with #variable interpolation.
  5. 5. A struct derives PartialOrd with fields major, minor, patch in that order. How are two values compared?

    Derived ordering is lexicographic in declaration order, so reordering fields changes the result.

Summary

  • Procedural macros are Rust functions from TokenStream to TokenStream, run by the compiler at build time. There are three kinds: derive, attribute and function-like.
  • #[derive(Trait)] adds an impl that applies the trait to each field, so every field type must implement the trait.
  • #[derive(Debug)] expands to debug_struct(...).field(...).finish(); you can write the same by hand when you need to hide or reshape output.
  • Derived PartialOrd/Ord compare fields in declaration order.
  • A proc macro lives in its own proc-macro = true crate and usually uses syn (parse) and quote (generate). That cannot run in our single-file editor, so those snippets are read-only.
  • serde shows the pattern at scale: derive plus helper attributes (#[serde(rename = ...)]).
  • Prefer functions, then macro_rules!, then proc macros, and use cargo expand when generated code surprises you.

Next: Attributes, cfg and Conditional Compilation