Rust Macro System

Also Known As

TL;DR

Explanation

Rust has two distinct macro systems that both run during compilation, expanding into ordinary Rust code before type checking and code generation. They are nothing like C's textual preprocessor: Rust macros operate on token streams and respect the language's syntax and hygiene rules, so they cannot silently capture or clobber identifiers from the call site.

Declarative macros, written with `macro_rules!`, match against patterns of tokens and emit code per matching arm. They use fragment specifiers such as `$x:expr`, `$t:ty`, `$i:ident`, and `$p:pat` to capture syntactic categories, and repetition operators like `$( ... )*` and `$( ... ),+` to handle variadic input. The standard library's `vec!`, `println!`, and `assert_eq!` are declarative macros. They are powerful for reducing boilerplate but are limited to pattern-driven expansion and can produce confusing errors when input does not match any arm.

Procedural macros are functions that take a `TokenStream` and return a `TokenStream`, giving full programmatic control over generated code. They come in three forms: derive macros (`#[derive(Serialize)]`), attribute macros (`#[route(GET, "/")]`), and function-like macros (`sql!(...)`). Procedural macros must live in their own crate marked with `proc-macro = true`, and the ecosystem relies on the `syn` crate to parse tokens into an AST and `quote` to build output, with `proc-macro2` bridging the types.

Hygiene is the feature that separates Rust macros from naive substitution. Identifiers introduced by a macro live in their own syntactic context, so a temporary variable a macro creates will not collide with a variable of the same name at the call site. This makes macros composable and safe in ways textual macros never are.

Macros are the right tool when you need code that varies in structure - implementing a trait for many types, building a domain-specific syntax, or eliminating repetitive impl blocks. They are the wrong tool when a generic function, trait, or const would do, because macros are harder to read, harder to debug (errors point at expanded code), slower to compile, and invisible to many IDE features. Reach for the simplest abstraction first and escalate to macros only when ordinary language features cannot express the pattern.

Common Misconception

Why It Matters

Common Mistakes

• Writing a macro_rules! macro for something a generic function or trait could express, adding complexity for no real benefit.
• Assuming macros substitute text like the C preprocessor and expecting them to capture or shadow call-site variables.
• Forgetting that procedural macros must live in a separate crate with proc-macro = true in Cargo.toml.
• Choosing the wrong fragment specifier (for example $x:expr where $x:ty is needed) and getting cryptic match failures.
• Mishandling repetition syntax so $( ... )* expands with the wrong separators or arity.

Avoid When

• A generic function, trait, or const can express the same behavior with clearer errors and better tooling support.
• The abstraction is needed only once and the macro adds indirection that obscures rather than clarifies the code.
• You are duplicating logic that could be shared through ordinary composition, since macro-generated code is harder to debug.
• Compile time and readability matter more than saving a few lines, because macros expand slowly and confuse IDEs.

When To Use

• Generating repetitive trait implementations across many types where generics cannot abstract the variation.
• Building variadic or DSL-like syntax such as vec!, format strings, or query builders.
• Deriving boilerplate like serialization or builders via derive macros instead of hand-writing each impl.
• Eliminating structural duplication that no function, generic, or const expression can capture.

Code Examples

// Using a macro to do what a generic function does cleanly.
macro_rules! max_of {
    ($a:expr, $b:expr) => {
        // Evaluates each argument twice: side effects run twice!
        if $a > $b { $a } else { $b }
    };
}

fn next() -> i32 {
    println!("called");
    5
}

fn main() {
    // next() is invoked twice because the macro inlines the expression.
    let m = max_of!(next(), 3);
    println!("{}", m);
}

// A generic function: arguments evaluated once, clear errors, IDE-friendly.
fn max_of<T: PartialOrd>(a: T, b: T) -> T {
    if a > b { a } else { b }
}

// Reserve macros for what functions cannot do, e.g. variadic construction.
macro_rules! string_vec {
    ( $( $item:expr ),* $(,)? ) => {
        vec![ $( $item.to_string() ),* ]
    };
}

fn next() -> i32 {
    println!("called");
    5
}

fn main() {
    // next() runs exactly once.
    let m = max_of(next(), 3);
    println!("{}", m);

    let names = string_vec!["a", "b", "c"];
    println!("{:?}", names);
}

References

• https://doc.rust-lang.org/book/ch19-06-macros.html
• https://doc.rust-lang.org/reference/macros-by-example.html
• https://doc.rust-lang.org/reference/procedural-macros.html
• https://veykril.github.io/tlborm/

Tags

Related Terms