Procedural Macros: Writing Compiler Plugins with syn and quote

23 min read

Quick Overview

A procedural macro is a small Rust program that runs inside the compiler: it receives your code as a stream of tokens, transforms it with ordinary Rust logic, and hands back new tokens that the compiler then type-checks like anything else. This is how #[derive(Serialize)], #[tokio::main], and sqlx::query! work — and writing your own is the closest Rust gets to TypeScript’s transformer plugins or Babel macros, except it is type-safe, hygienic, and has zero runtime cost. This page covers the mechanics: the special proc-macro crate type, the TokenStream type, and the syn 2 + quote + proc-macro2 trio you will use for every nontrivial proc macro, ending with a full compile-verified custom derive.

Note: The current stable toolchain is Rust 1.96.0 on the 2024 edition; cargo new selects the newest edition automatically. Every Rust snippet here was compiled and run on stable with syn 2.0.117, quote 1.0.45, and proc-macro2 1.0.106.

Tip: If you have not read Macro Basics and Derive Macros yet, do so first. This page assumes you know that macros are compile-time, token-based, and hygienic, and that #[derive(...)] is one of the three procedural-macro flavors.

TypeScript/JavaScript Example

There is nothing in plain TypeScript that operates on your code the way a proc macro does. The nearest cousins are AST transformers — a TypeScript compiler transform, a Babel plugin, or a tool like babel-plugin-macros. They parse source into an Abstract Syntax Tree, walk and rewrite nodes, and print code back out. Here is a hand-written Babel-style transform that auto-generates a describe() method onto a class:

1
// babel-style transformer (runs in the BUILD step, on the AST).
2
import type { PluginObj, types as BabelTypes } from "@babel/core";
3

4
export default function addDescribe({ types: t }: { types: typeof BabelTypes }): PluginObj {
5
  return {
6
    name: "add-describe",
7
    visitor: {
8
      ClassDeclaration(path) {
9
        const className = path.node.id?.name ?? "Anonymous";
10

11
        // Collect the names of class fields from the AST.
12
        const fieldNames = path.node.body.body
13
          .filter((m) => t.isClassProperty(m) && t.isIdentifier(m.key))
14
          .map((m) => ((m as BabelTypes.ClassProperty).key as BabelTypes.Identifier).name);
15

16
        // Build the body of a `describe()` method as a template string.
17
        const lines = fieldNames
18
          .map((f) => `lines.push(\`  ${f} = \${JSON.stringify(this.${f})}\`);`)
19
          .join("\n");
20
        const methodSrc = `
21
          describe() {
22
            const lines = ["${className} {"];
23
            ${lines}
24
            lines.push("}");
25
            return lines.join("\\n");
26
          }`;
27

28
        // Parse that string and splice the new method into the class.
29
        const method = t.classMethod(/* ...build from methodSrc... */);
30
        path.node.body.body.push(method);
31
      },
32
    },
33
  };
34
}

A user of the plugin writes a normal class and the build step injects the method:

1
class User {
2
  id = 0;
3
  name = "";
4
  active = false;
5
}
6
// After transform, `new User().describe()` exists at runtime.

Two things to hold onto. First, the transform manipulates an AST (ClassDeclaration, ClassProperty, Identifier) — exactly what syn gives you in Rust. Second, when this Babel plugin builds new code it does it by string concatenation (methodSrc), which is fragile: a stray brace or an unescaped value silently produces broken output, and nothing checks the result until runtime.

Rust Equivalent

The Rust version is a separate crate of the special proc-macro type. It parses the input with syn, builds output with quote! (structured token interpolation, not string concatenation), and the compiler type-checks the generated code immediately.

The macro crate, describe_derive/src/lib.rs:

1
use proc_macro::TokenStream;
2
use quote::quote;
3
use syn::{parse_macro_input, Data, DeriveInput, Fields};
4

5
/// Derives a `describe(&self) -> String` method that lists each field
6
/// name and its `Debug` value — the Rust analogue of the Babel plugin.
7
#[proc_macro_derive(Describe)]
8
pub fn derive_describe(input: TokenStream) -> TokenStream {
9
    // 1. PARSE the incoming tokens into a typed syntax tree.
10
    let ast = parse_macro_input!(input as DeriveInput);
11
    let name = &ast.ident;
12

13
    // 2. INSPECT: require a struct with named fields, or emit a real error.
14
    let fields = match &ast.data {
15
        Data::Struct(data) => match &data.fields {
16
            Fields::Named(named) => &named.named,
17
            _ => {
18
                return syn::Error::new_spanned(
19
                    &ast.ident,
20
                    "Describe only supports structs with named fields",
21
                )
22
                .to_compile_error()
23
                .into();
24
            }
25
        },
26
        _ => {
27
            return syn::Error::new_spanned(
28
                &ast.ident,
29
                "Describe can only be derived for structs",
30
            )
31
            .to_compile_error()
32
            .into();
33
        }
34
    };
35

36
    // 3. BUILD one push_str line per field. `quote!` interpolates with `#`.
37
    let field_lines = fields.iter().map(|field| {
38
        let field_name = field.ident.as_ref().unwrap();
39
        let field_label = field_name.to_string();
40
        quote! {
41
            out.push_str(&format!("  {} = {:?}\n", #field_label, &self.#field_name));
42
        }
43
    });
44

45
    let type_label = name.to_string();
46

47
    // 4. EMIT a complete `impl` block as new tokens.
48
    let expanded = quote! {
49
        impl #name {
50
            pub fn describe(&self) -> String {
51
                let mut out = String::new();
52
                out.push_str(&format!("{} {{\n", #type_label));
53
                #( #field_lines )*
54
                out.push('}');
55
                out
56
            }
57
        }
58
    };
59

60
    expanded.into()
61
}

Its Cargo.toml — note the proc-macro = true flag, which makes this a compiler-plugin crate:

1
[package]
2
name = "describe_derive"
3
version = "0.1.0"
4
edition = "2024"
5

6
[lib]
7
proc-macro = true
8

9
[dependencies]
10
syn = "2"
11
quote = "1"
12
proc-macro2 = "1"

A separate consumer crate uses it like any built-in derive:

1
use describe_derive::Describe;
2

3
#[derive(Describe)]
4
struct User {
5
    id: u64,
6
    name: String,
7
    active: bool,
8
}
9

10
fn main() {
11
    let u = User { id: 7, name: "Ada".to_string(), active: true };
12
    println!("{}", u.describe());
13
}

Real output:

1
User {
2
  id = 7
3
  name = "Ada"
4
  active = true
5
}

Unlike the Babel plugin’s methodSrc string, the quote! { ... } block is parsed by the quote crate into structured tokens; a malformed interpolation is a compile error in the macro crate, and the generated impl is type-checked in the consumer crate. Nothing reaches runtime unchecked.

Detailed Explanation

The three crates: proc-macro, proc-macro2, and the syn/quote pair

Proc macros are built on three layers. Getting them straight removes most of the early confusion:

proc_macro is a crate baked into the compiler (no cargo add needed). It defines proc_macro::TokenStream, the type your macro functions must take and return. It only exists while the compiler is running, so you cannot use it in a regular binary, a test, or a build script.
proc-macro2 (crates.io) is a mirror of that API that works anywhere — in unit tests, build scripts, and on the host. Its proc_macro2::TokenStream is what syn and quote actually speak. You convert between the two with .into().
syn parses a TokenStream into a typed syntax tree (DeriveInput, ItemFn, Expr, …), and quote does the reverse: it turns a template with #interpolation into a TokenStream. They are by the same author (dtolnay) and are the de-facto standard.

The data flow of every proc macro is the same pipeline:

1
proc_macro::TokenStream  --.into()-->  proc_macro2::TokenStream
2
        (compiler)                            |
3
                                         syn::parse2 / parse_macro_input!
4
                                              v
5
                                      typed AST (DeriveInput, ...)
6
                                              |
7
                                         your Rust logic
8
                                              v
9
                                       quote! { ... }  --> proc_macro2::TokenStream
10
                                              |
11
proc_macro::TokenStream  <--.into()-----------'
12
        (back to compiler)

What a `TokenStream` actually is

A TokenStream is a flat sequence of token trees: identifiers, literals, punctuation, and delimited groups ((...), [...], {...}) which nest. It is not a string and not a fully parsed AST — it sits between the two. For struct User { id: u64 } the stream is roughly the tokens struct, User, and a brace-group containing id, :, u64. Crucially, every token carries a span: a record of where it came from in the source, which drives both error messages and hygiene (see Macro Basics). Because the input is already tokenized — not raw text — quote! cannot accidentally glue two identifiers together, and :expr-style grouping is preserved automatically.

You can build and inspect a proc_macro2::TokenStream entirely on the host, which is why the standalone demo below runs as a normal binary:

1
use proc_macro2::TokenStream;
2
use quote::quote;
3
use syn::DeriveInput;
4

5
fn main() {
6
    // `quote!` builds a proc_macro2::TokenStream from a template.
7
    let source: TokenStream = quote! {
8
        struct Point { x: i32, y: i32 }
9
    };
10

11
    // `syn::parse2` parses tokens into a typed AST node.
12
    let ast: DeriveInput = syn::parse2(source).expect("valid struct");
13
    println!("parsed type name: {}", ast.ident);
14

15
    // Build new tokens and render them back to a string.
16
    let name = ast.ident;
17
    let generated: TokenStream = quote! {
18
        impl #name {
19
            fn type_name() -> &'static str { stringify!(#name) }
20
        }
21
    };
22
    println!("generated tokens: {generated}");
23
}

Run as an ordinary binary (dependencies: syn with the full feature, quote, proc-macro2). Real output:

1
parsed type name: Point
2
generated tokens: impl Point { fn type_name () -> & 'static str { stringify ! (Point) } }

Notice the Display of a TokenStream re-inserts spaces between every token — it is for debugging, not for pretty source. (For readable output, pipe through cargo expand.)

Walking the `Describe` derive line by line

#[proc_macro_derive(Describe)] registers a derive macro named Describe. The function it decorates must have the signature fn(TokenStream) -> TokenStream and live at the crate root of a proc-macro crate. The function name (derive_describe) is irrelevant to users; the Describe in the attribute is what they write in #[derive(Describe)].

parse_macro_input!(input as DeriveInput) parses the token stream into syn’s DeriveInput — the catch-all node for “the thing a derive is attached to” (a struct, enum, or union). Unlike syn::parse2, this macro is purpose-built for proc-macro entry points: on a parse error it returns a compile_error! invocation from your function automatically, so you never hand back garbage tokens.

Matching on ast.data distinguishes Data::Struct, Data::Enum, and Data::Union. We only support named-field structs, so every other shape produces a deliberate error via syn::Error::new_spanned(&ast.ident, "...").to_compile_error(). Passing &ast.ident as the span means the error underlines the type name in the user’s code, not some location inside our macro.

Building field_lines maps over each field to produce a small TokenStream fragment. Inside quote!, #field_label interpolates the field’s name as a string literal and #field_name interpolates the identifier so self.#field_name becomes e.g. self.id. These fragments are themselves tokens, so they compose.

The final quote! assembles the impl block. The repetition #( #field_lines )* — analogous to macro_rules! repetition from Repetition — splices every fragment in sequence. Then .into() converts the proc_macro2::TokenStream that quote! produced back into the proc_macro::TokenStream the compiler expects.

Seeing the generated code with `cargo expand`

You never have to guess what your macro emits. cargo install cargo-expand, then cargo expand prints the post-expansion source. For the User above, the relevant portion is:

1
impl User {
2
    pub fn describe(&self) -> String {
3
        let mut out = String::new();
4
        out.push_str(&format!("{} {{\n", "User"));
5
        out.push_str(&format!("  {} = {:?}\n", "id", &self.id));
6
        out.push_str(&format!("  {} = {:?}\n", "name", &self.name));
7
        out.push_str(&format!("  {} = {:?}\n", "active", &self.active));
8
        out.push('}');
9
        out
10
    }
11
}

(In the raw cargo expand output the format! calls are themselves further expanded into ::alloc::fmt::format(format_args!(...)), because every macro is expanded — format! included. The shape above is the meaningful part.)

Key Differences

Concept	TypeScript AST transform (Babel/ts plugin)	Rust procedural macro
When it runs	Build step, as a separate Node process	Inside `rustc`, during compilation
Input	AST nodes from the parser	`TokenStream` (token trees, not full AST)
Parsing	Done for you by the compiler	You call `syn` to parse tokens into an AST
Output construction	String templating or AST builders	`quote!` structured interpolation
Output checking	Re-parsed; type errors surface at runtime	Type-checked immediately as real Rust
Hygiene	Manual; name clashes are your problem	Span-based hygiene built in
Distribution	An npm package + build config	A crate with `proc-macro = true`
Runtime cost	The generated JS runs at runtime	Zero — only generated code remains

All procedural macros use syn/quote/proc-macro2; they differ only in their entry-point attribute and signature:

Flavor	Attribute	Signature	Invoked as	Covered in
Custom derive	`#[proc_macro_derive(Name)]`	`fn(TokenStream) -> TokenStream`	`#[derive(Name)]`	Derive Macros
Attribute	`#[proc_macro_attribute]`	`fn(TokenStream, TokenStream) -> TokenStream`	`#[name(args)]`	Attribute Macros
Function-like	`#[proc_macro]`	`fn(TokenStream) -> TokenStream`	`name!(...)`	Function-like Macros

A derive macro adds code alongside the item it annotates (it never sees the item replaced). An attribute macro receives both its arguments and the entire annotated item, and returns whatever should replace it. A function-like macro receives only the tokens between its delimiters.

Why a separate crate?

A proc-macro crate is compiled for the compiler’s own host and loaded as a plugin while it compiles your other crates. That is a fundamentally different compilation target from your application, so the macro logic must live in its own crate that only exports macros (this is enforced — see the pitfalls). The common pattern in published libraries is a pair: a foo_derive proc-macro crate and a foo crate that re-exports it, so users only depend on foo. serde does exactly this with serde and serde_derive.

Common Pitfalls

Pitfall 1: Putting a proc macro in a normal crate

The #[proc_macro_derive] family is only legal in a crate with proc-macro = true. Forget the flag and you get two errors at once:

1
// in a crate WITHOUT `proc-macro = true` in Cargo.toml
2
use proc_macro::TokenStream; // does not compile (error E0432)
3

4
#[proc_macro_derive(Oops)] // does not compile
5
pub fn derive_oops(_input: TokenStream) -> TokenStream {
6
    TokenStream::new()
7
}

Real compiler errors:

1
error: the `#[proc_macro_derive]` attribute is only usable with crates of the `proc-macro` crate type
2
 --> src/lib.rs:3:1
3
  |
4
3 | #[proc_macro_derive(Oops)]
5
  | ^^^^^^^^^^^^^^^^^^^^^^^^^^
6

7
error[E0432]: unresolved import `proc_macro`
8
 --> src/lib.rs:1:5
9
  |
10
1 | use proc_macro::TokenStream;
11
  |     ^^^^^^^^^^ use of unresolved module or unlinked crate `proc_macro`

The fix is to add [lib] with proc-macro = true to the crate’s Cargo.toml. The proc_macro crate only becomes importable once that flag is set.

Pitfall 2: Confusing `proc_macro::TokenStream` with `proc_macro2::TokenStream`

These are two distinct types with the same name. syn and quote produce proc_macro2::TokenStream, but your entry point must return proc_macro::TokenStream. Forget the .into() and:

1
// inside #[proc_macro_derive], returning the quote! result directly:
2
    let expanded = quote! { /* ... */ };
3
    expanded // does not compile (error E0308) — missing `.into()`

Real compiler error (excerpt):

1
error[E0308]: mismatched types
2
   --> describe_derive/src/lib.rs:54:5
3
    |
4
  6 | pub fn derive_describe(input: TokenStream) -> TokenStream {
5
    |                                               ----------- expected `proc_macro::TokenStream` because of return type
6
...
7
 54 |     expanded
8
    |     ^^^^^^^^ expected `proc_macro::TokenStream`, found `proc_macro2::TokenStream`
9
    |
10
    = note: `proc_macro2::TokenStream` and `proc_macro::TokenStream` have similar names, but are actually distinct types
11
help: call `Into::into` on this expression to convert `proc_macro2::TokenStream` into `proc_macro::TokenStream`
12
    |
13
 54 |     expanded.into()
14
    |             +++++++

The compiler even suggests the fix: expanded.into(). A clean convention is to keep all internal logic in proc_macro2 and only convert at the very edges of the entry function.

Pitfall 3: Returning a parse error as a panic instead of `compile_error!`

A tempting but bad habit is let ast = syn::parse2(input).unwrap();. If parsing fails, your macro panics, and the user sees an opaque “proc-macro panicked” message with no useful span. Instead, return errors as tokens: syn::Error has .to_compile_error() (one error) and .into_compile_error() (consuming form), and parse_macro_input! does this for you automatically. Always propagate errors through the token stream so the user gets a real, located diagnostic pointing at their code — as the Describe derive does for enums (see Pitfall 4).

Pitfall 4: Forgetting to handle struct shapes (and emitting a vague error)

If you only handle named-field structs, decide what happens for everything else. The Describe derive returns a clear compile_error! for enums. With it applied to an enum:

1
#[derive(Describe)] // does not compile — Describe rejects enums on purpose
2
enum Shape {
3
    Circle,
4
    Square,
5
}

Real compiler error:

1
error: Describe can only be derived for structs
2
 --> consumer/src/main.rs:4:6
3
  |
4
4 | enum Shape {
5
  |      ^^^^^

Because we built the error with new_spanned(&ast.ident, ...), it underlines Shape — the user’s type — instead of something inside the macro. Compare that to an unwrapped panic, which would point nowhere useful.

Pitfall 5: Slow iteration and forgetting the `full` feature

syn is feature-gated to keep compile times down. The default features parse derive inputs and types; parsing whole function bodies, expressions, or statements needs features = ["full"]. If syn::parse2::<ItemFn>(...) fails to resolve or behaves oddly, check that you enabled full. And because every edit to a proc-macro crate recompiles syn, keep the macro crate small and test the pure logic with proc-macro2 (next section) rather than recompiling the whole consumer each time.

Best Practices

Split a testable core from the thin entry point

The proc_macro types cannot be used outside the compiler, so wrap them at the boundary and put all real logic in a function over proc_macro2::TokenStream. That core is unit-testable like any function:

1
use proc_macro::TokenStream;
2
use proc_macro2::TokenStream as TokenStream2;
3
use quote::quote;
4
use syn::{parse2, DeriveInput};
5

6
// Thin shim: convert, delegate, convert back. The only `proc_macro` contact.
7
#[proc_macro_derive(Named)]
8
pub fn derive_named(input: TokenStream) -> TokenStream {
9
    expand(input.into())
10
        .unwrap_or_else(syn::Error::into_compile_error)
11
        .into()
12
}
13

14
// Pure core: uses only proc_macro2, so it runs on the host and in tests.
15
fn expand(input: TokenStream2) -> syn::Result<TokenStream2> {
16
    let ast: DeriveInput = parse2(input)?;
17
    let name = &ast.ident;
18
    let label = name.to_string();
19
    Ok(quote! {
20
        impl #name {
21
            pub fn type_name(&self) -> &'static str { #label }
22
        }
23
    })
24
}
25

26
#[cfg(test)]
27
mod tests {
28
    use super::expand;
29
    use quote::quote;
30

31
    #[test]
32
    fn generates_type_name_impl() {
33
        let input = quote! { struct Widget { id: u32 } };
34
        let output = expand(input).unwrap().to_string();
35
        assert!(output.contains("impl Widget"));
36
        assert!(output.contains("\"Widget\""));
37
    }
38
}

Real output of cargo test -p on this crate:

1
running 1 test
2
test tests::generates_type_name_impl ... ok
3

4
test result: ok. 1 passed; 0 failed; 0 ignored; 0 measured; 0 filtered out

Note how expand returns syn::Result<TokenStream2> and the shim funnels any error into into_compile_error(). This is the idiomatic shape used across the ecosystem. (For end-to-end tests that check the macro produces a compile error on bad input, reach for trybuild; see Testing.)

Always preserve generics

A derive that assumes the type has no generics breaks the moment someone writes struct Wrapper<T>. syn makes this trivial with split_for_impl, which yields the three pieces an impl needs:

1
let (impl_generics, ty_generics, where_clause) = ast.generics.split_for_impl();
2
let expanded = quote! {
3
    impl #impl_generics #name #ty_generics #where_clause {
4
        // ...
5
    }
6
};

This expands to impl<T> Wrapper<T> where ... { ... } automatically. If your impl requires a bound on each type parameter (e.g. T: Debug), add it to ast.generics before splitting.

Use helper attributes instead of magic conventions

When a derive needs per-field configuration, declare inert helper attributes in the attributes(...) list rather than inventing naming conventions. This is exactly how serde offers #[serde(rename = "...")]. The Real-World Example below shows the full pattern with attr.parse_nested_meta.

Point spans at the user’s code, and prefer `quote_spanned!` for generated bounds

Every diagnostic your macro emits should underline something in their source. Use syn::Error::new_spanned(&offending_node, msg) so the squiggle lands on the right token. When generated code itself can fail to compile (a missing trait bound, say), quote_spanned! lets you attribute that failure to a meaningful user span instead of an opaque macro location.

Real-World Example

A production-flavored custom derive, Report, that turns a struct into a human-readable report and supports two helper attributes: #[report(label = "...")] to rename a field and #[report(skip)] to omit a sensitive field. This mirrors how real derives (serde, clap) are configured per field.

The macro crate, report_derive/src/lib.rs (with proc-macro = true and the same syn/quote/proc-macro2 dependencies):

1
use proc_macro::TokenStream;
2
use quote::quote;
3
use syn::{parse_macro_input, Data, DeriveInput, Fields, LitStr};
4

5
/// Derives `report(&self) -> String`. Configure per field with
6
/// `#[report(label = "Nice Name")]` and `#[report(skip)]`.
7
#[proc_macro_derive(Report, attributes(report))]
8
pub fn derive_report(input: TokenStream) -> TokenStream {
9
    let ast = parse_macro_input!(input as DeriveInput);
10
    let name = &ast.ident;
11

12
    // let-else gives a clean early exit with a real compile error.
13
    let Data::Struct(data) = &ast.data else {
14
        return syn::Error::new_spanned(name, "Report can only be derived for structs")
15
            .to_compile_error()
16
            .into();
17
    };
18
    let Fields::Named(fields) = &data.fields else {
19
        return syn::Error::new_spanned(name, "Report needs named fields")
20
            .to_compile_error()
21
            .into();
22
    };
23

24
    let mut lines = Vec::new();
25
    for field in &fields.named {
26
        let ident = field.ident.as_ref().unwrap();
27
        let mut label = ident.to_string();
28
        let mut skip = false;
29

30
        // Parse each `#[report(...)]` helper attribute on this field.
31
        for attr in &field.attrs {
32
            if !attr.path().is_ident("report") {
33
                continue;
34
            }
35
            let parsed = attr.parse_nested_meta(|meta| {
36
                if meta.path.is_ident("skip") {
37
                    skip = true;
38
                    Ok(())
39
                } else if meta.path.is_ident("label") {
40
                    let value: LitStr = meta.value()?.parse()?;
41
                    label = value.value();
42
                    Ok(())
43
                } else {
44
                    Err(meta.error("unknown `report` option"))
45
                }
46
            });
47
            if let Err(e) = parsed {
48
                return e.to_compile_error().into();
49
            }
50
        }
51

52
        if skip {
53
            continue;
54
        }
55
        lines.push(quote! {
56
            rows.push(format!("{}: {:?}", #label, &self.#ident));
57
        });
58
    }
59

60
    let expanded = quote! {
61
        impl #name {
62
            pub fn report(&self) -> String {
63
                let mut rows: Vec<String> = Vec::new();
64
                #( #lines )*
65
                rows.join("\n")
66
            }
67
        }
68
    };
69
    expanded.into()
70
}

The consumer crate:

1
use report_derive::Report;
2

3
#[derive(Report)]
4
struct Account {
5
    #[report(label = "Account ID")]
6
    id: u64,
7
    #[report(label = "Owner")]
8
    owner: String,
9
    #[report(skip)]
10
    #[allow(dead_code)] // never read because `report` skips it
11
    password_hash: String,
12
}
13

14
fn main() {
15
    let acct = Account {
16
        id: 42,
17
        owner: "Grace".to_string(),
18
        password_hash: "do-not-print".to_string(),
19
    };
20
    println!("{}", acct.report());
21
}

Real output:

1
Account ID: 42
2
Owner: "Grace"

The password_hash field is omitted entirely because of #[report(skip)], and the two visible fields use their custom labels. The key API is attr.parse_nested_meta, the syn 2 way to walk the comma-separated options inside #[report(...)]: meta.path.is_ident("skip") matches a bare flag, while meta.value()?.parse::<LitStr>()? reads the right-hand side of label = "...". Anything unrecognized returns meta.error(...), which surfaces as a located compile error on the user’s attribute — never a panic.

Note: syn 2.0 replaced the older 1.x Attribute::parse_meta / NestedMeta API with Meta plus parse_nested_meta. If you find a tutorial using NestedMeta or AttributeArgs, it targets syn 1 and will not compile against syn 2. Always check the version.

Exercises

Exercise 1

Difficulty: Easy

Objective: Get a proc-macro crate building and prove the entry-point conversion to yourself.

Instructions: Create a proc-macro crate that exposes a #[proc_macro_derive(TypeName)] macro generating a type_name(&self) -> &'static str method returning the struct’s name as a string literal. You do not need to inspect fields. Apply it to a struct in a consumer crate and print the result. Remember the [lib] proc-macro = true flag and the final .into().

1
use proc_macro::TokenStream;
2
use quote::quote;
3
use syn::{parse_macro_input, DeriveInput};
4

5
#[proc_macro_derive(TypeName)]
6
pub fn derive_type_name(input: TokenStream) -> TokenStream {
7
    // TODO: parse, grab the ident, emit an impl with a type_name method
8
    todo!()
9
}

Solution

1
// type_name_derive/src/lib.rs  (crate has `proc-macro = true`, deps: syn 2, quote 1)
2
use proc_macro::TokenStream;
3
use quote::quote;
4
use syn::{parse_macro_input, DeriveInput};
5

6
#[proc_macro_derive(TypeName)]
7
pub fn derive_type_name(input: TokenStream) -> TokenStream {
8
    let ast = parse_macro_input!(input as DeriveInput);
9
    let name = &ast.ident;
10
    let label = name.to_string();
11
    let expanded = quote! {
12
        impl #name {
13
            pub fn type_name(&self) -> &'static str { #label }
14
        }
15
    };
16
    expanded.into()
17
}

1
use type_name_derive::TypeName;
2

3
#[derive(TypeName)]
4
struct Widget {
5
    #[allow(dead_code)]
6
    id: u32,
7
}
8

9
fn main() {
10
    let w = Widget { id: 1 };
11
    println!("{}", w.type_name());
12
}

Output:

1
Widget

The #label interpolates the type name as a string literal; .into() converts the quote! result to the proc_macro::TokenStream the signature demands.

Exercise 2

Difficulty: Medium

Objective: Write a function-like procedural macro and parse a literal from its input — a different entry point from a derive.

Instructions: Add a #[proc_macro] function stars so that stars!(5) expands to the &str literal "*****", computed at compile time. Parse the input as a syn::LitInt, read it with base10_parse::<usize>(), build the string, and emit it as a literal with quote!. Verify stars!(5) prints five stars.

1
use proc_macro::TokenStream;
2
use quote::quote;
3
use syn::{parse_macro_input, LitInt};
4

5
#[proc_macro]
6
pub fn stars(input: TokenStream) -> TokenStream {
7
    // TODO: parse a LitInt, repeat "*", emit the &str literal
8
    todo!()
9
}

Solution

1
// in a `proc-macro = true` crate (deps: syn 2, quote 1, proc-macro2 1)
2
use proc_macro::TokenStream;
3
use quote::quote;
4
use syn::{parse_macro_input, LitInt};
5

6
#[proc_macro]
7
pub fn stars(input: TokenStream) -> TokenStream {
8
    let n = parse_macro_input!(input as LitInt);
9
    let count: usize = n.base10_parse().unwrap();
10
    let s = "*".repeat(count);
11
    quote! { #s }.into()
12
}

1
// consumer
2
use star_macro::stars;
3

4
fn main() {
5
    const BANNER: &str = stars!(5);
6
    println!("banner = {BANNER}");
7
}

Output:

1
banner = *****

Because the string is built during compilation, BANNER is a genuine &'static str constant — there is no runtime work. See Function-like Macros for more on this flavor.

Exercise 3

Difficulty: Hard

Objective: Inspect fields and handle generics correctly with split_for_impl.

Instructions: Write a #[proc_macro_derive(FieldCount)] that adds an associated constant FIELD_COUNT: usize equal to the number of fields, and that works for generic structs such as Pair<T>. Count named, unnamed (tuple-struct), and unit shapes. Use ast.generics.split_for_impl() so the generated impl carries the type parameters. Verify Pair::<i32>::FIELD_COUNT == 2.

1
use proc_macro::TokenStream;
2
use quote::quote;
3
use syn::{parse_macro_input, Data, DeriveInput, Fields};
4

5
#[proc_macro_derive(FieldCount)]
6
pub fn derive_field_count(input: TokenStream) -> TokenStream {
7
    // TODO: count fields by shape, split generics, emit `const FIELD_COUNT`
8
    todo!()
9
}

Solution

1
// in a `proc-macro = true` crate (deps: syn 2, quote 1, proc-macro2 1)
2
use proc_macro::TokenStream;
3
use quote::quote;
4
use syn::{parse_macro_input, Data, DeriveInput, Fields};
5

6
#[proc_macro_derive(FieldCount)]
7
pub fn derive_field_count(input: TokenStream) -> TokenStream {
8
    let ast = parse_macro_input!(input as DeriveInput);
9
    let name = &ast.ident;
10
    let (impl_generics, ty_generics, where_clause) = ast.generics.split_for_impl();
11

12
    let count = match &ast.data {
13
        Data::Struct(d) => match &d.fields {
14
            Fields::Named(f) => f.named.len(),
15
            Fields::Unnamed(f) => f.unnamed.len(),
16
            Fields::Unit => 0,
17
        },
18
        _ => 0,
19
    };
20

21
    quote! {
22
        impl #impl_generics #name #ty_generics #where_clause {
23
            pub const FIELD_COUNT: usize = #count;
24
        }
25
    }
26
    .into()
27
}

1
// consumer
2
use field_count_derive::FieldCount;
3

4
#[derive(FieldCount)]
5
struct Pair<T> {
6
    #[allow(dead_code)]
7
    first: T,
8
    #[allow(dead_code)]
9
    second: T,
10
}
11

12
fn main() {
13
    println!("Pair<i32> has {} fields", Pair::<i32>::FIELD_COUNT);
14
}

Output:

1
Pair<i32> has 2 fields

split_for_impl produces the three fragments that expand to impl<T> Pair<T> { ... }. Without it, the generated impl Pair { ... } would fail to compile for any generic type, because Pair alone is not a complete type. The field count is a compile-time usize constant baked into the binary.

Procedural Macros: Writing Compiler Plugins with syn and quote

Quick Overview

TypeScript/JavaScript Example

Rust Equivalent

Detailed Explanation

The three crates: proc-macro, proc-macro2, and the syn/quote pair

What a `TokenStream` actually is

Walking the `Describe` derive line by line

Seeing the generated code with `cargo expand`

Key Differences

Why a separate crate?

Common Pitfalls

Pitfall 1: Putting a proc macro in a normal crate

Pitfall 2: Confusing `proc_macro::TokenStream` with `proc_macro2::TokenStream`

Pitfall 3: Returning a parse error as a panic instead of `compile_error!`

Pitfall 4: Forgetting to handle struct shapes (and emitting a vague error)

Pitfall 5: Slow iteration and forgetting the `full` feature

Best Practices

Split a testable core from the thin entry point

Always preserve generics

Use helper attributes instead of magic conventions

Point spans at the user’s code, and prefer `quote_spanned!` for generated bounds

Real-World Example

Further Reading

Official documentation

Exercises

Exercise 1

Exercise 2

Exercise 3

Procedural Macros: Writing Compiler Plugins with syn and quote

Quick Overview

TypeScript/JavaScript Example

Rust Equivalent

Detailed Explanation

The three crates: proc-macro, proc-macro2, and the syn/quote pair

What a TokenStream actually is

Walking the Describe derive line by line

Seeing the generated code with cargo expand

Key Differences

Three flavors share one foundation

Why a separate crate?

Common Pitfalls

Pitfall 1: Putting a proc macro in a normal crate

Pitfall 2: Confusing proc_macro::TokenStream with proc_macro2::TokenStream

Pitfall 3: Returning a parse error as a panic instead of compile_error!

Pitfall 4: Forgetting to handle struct shapes (and emitting a vague error)

Pitfall 5: Slow iteration and forgetting the full feature

Best Practices

Split a testable core from the thin entry point

Always preserve generics

Use helper attributes instead of magic conventions

Point spans at the user’s code, and prefer quote_spanned! for generated bounds

Real-World Example

Further Reading

Official documentation

Related sections in this guide

Exercises

Exercise 1

Exercise 2

Exercise 3

What a `TokenStream` actually is

Walking the `Describe` derive line by line

Seeing the generated code with `cargo expand`

Pitfall 2: Confusing `proc_macro::TokenStream` with `proc_macro2::TokenStream`

Pitfall 3: Returning a parse error as a panic instead of `compile_error!`

Pitfall 5: Slow iteration and forgetting the `full` feature

Point spans at the user’s code, and prefer `quote_spanned!` for generated bounds