Rust macros

Every quoted message and number below comes from rustc, cargo, and Clippy 1.98.1, edition 2024.

Decide whether you need a macro

A macro costs compile time, a second crate in the procedural case, diagnostics that point at the invocation instead of the defect, and an IDE that cannot look inside. Take a non-macro row when one fits.

Do not copy nightly macro syntax. As of Rust 1.98.1, a macro_rules! arm written attr() (...) => ... fails with error[E0658]: `macro_rules!` attributes are unstable, an arm written derive() (...) => ... fails with error[E0658]: `macro_rules!` derives are unstable, and ${count($x)} fails with error[E0658]: meta-variable expressions are unstable.

Route the symptom

Read the expansion and verify

Read the expansion before you reason about why a macro fails.

# Nightly toolchain. Prints the whole crate after expansion.
cargo +nightly rustc --locked -p <crate> --profile=check -- -Zunpretty=expanded

# One file, no cargo.
rustc +nightly --edition 2024 -Zunpretty=expanded src/main.rs

# Works on the stable toolchain: it sets RUSTC_BOOTSTRAP=1 for the -Zunpretty call.
cargo install --locked cargo-expand
cargo expand --locked --package <crate> <path::to::item>

Expansion to text is lossy: it prints hygienic identifiers as plain names. Do not paste the output back as source. It can fail to compile, or compile and behave differently.

rustc does not report most lints, for example unused_variables and unsafe_code, in the expansion of another crate's macro. Lint the expansion through an invocation inside the defining crate.

Set up trybuild with trybuild = "1" under [dev-dependencies] and a #[test] that calls trybuild::TestCases::new().compile_fail("tests/ui/*.rs"). Run TRYBUILD=overwrite cargo test --locked to write the .stderr files, and review each one before you commit it.

A green run proves only the input shapes you tested. Add one case per supported shape: a generic type, a PhantomData<T> field, a unit struct, and each rejected shape. Read references/review-checklist.md when you review a finished macro change.

Emit absolute paths

A macro expands in the caller's module. Every path in its output resolves there, against the caller's imports and local items.

Emit ::dep_name:: only for a crate that the caller must depend on directly, such as the facade. A tests/*.rs invocation does not catch a ::dep_name:: path, because an integration test sees every dependency of its package. Do not put $crate:: in front of a path the caller passed in as a metavariable. That path names an item in the caller's crate.

A missing $crate passes in one place only: a module of the defining crate that already has the item in scope. It fails in every downstream crate, in a #[cfg(test)] mod tests that does not use super::*, and in your own tests/*.rs. A bare standard-library name fails only in a caller that shadows it, for example E0107 on a bare Result<T, E> under a caller's type Result<T> alias. Read references/declarative-macros.md when you need that reproduction as a test. A derive macro follows the same rule with ::facade::Trait paths; see references/derive-macro-crates.md.

Keep caller expressions out of unsafe blocks

unsafe { f($e) } evaluates the caller's expression $e inside your unsafe block, so the caller can write unsafe operations with no unsafe keyword at the call site. Evaluate each metavariable into a local before the block: let v = $e;, then unsafe { f(v) }. clippy::macro_metavars_in_unsafe flags the unbound form. It fires only on an invocation in the defining crate, such as a #[cfg(test)] mod tests; an invocation in tests/*.rs does not trigger it. By default the lint checks only #[macro_export] macros. For a private macro, set warn-unsafe-macro-metavars-in-private-macros = true in clippy.toml.

A local does not help when the block's soundness depends on the value the caller passes. Then emit a call to an unsafe fn outside any unsafe block, so the caller must write unsafe.

A downstream #![forbid(unsafe_code)] does not reject an unsafe block that another crate's macro emits. The macro crate owns the soundness of every unsafe block in its expansion.

Scope is textual

A macro_rules! macro is the one item in Rust whose definition must appear before its use in source order. A refactor that moves the definition down the file breaks the build, and the message names no missing import.

error: cannot find macro `hello` in this scope
  |             ^^^^^ consider moving the definition of `hello` before this call
note: a macro with the same name exists, but it appears later

The same rule applies across modules. A macro defined in mod a is invisible in mod b, even when b comes later:

error: cannot find macro `only_here` in this scope
  = help: have you added the `#[macro_use]` on the module/import?

Four ways to widen the scope. Prefer the first: it keeps the macro private and needs no crate-root placement.

#[macro_export] puts the macro in the public API of the crate and at its root. Do not reach for it to cross a module boundary inside one crate.

Hygiene stops at bindings

Hygiene is not a general namespace shield. It covers exactly the identifiers rustc can rename.

A generated local is invisible to the caller: E0425 with help: an identifier with the same name is defined here, but is not accessible due to macro hygiene. A fixed item name collides on the second invocation with error[E0428]: the name `Inner` is defined multiple times.

Two fixes. Derive every generated item name from a metavariable, or wrap the private helpers in an anonymous const _: () = { ... }; block. Each expansion of that block gets its own item namespace, and an impl inside it still applies to the outer type. Read references/declarative-macros.md when you need the reproductions or a working const _ example.

Fragment specifiers

Follow sets are checked at definition time

rustc rejects an illegal token sequence when it reads the macro_rules! item, before anyone invokes the macro. Design the separators before you write the arms. Only =>, ,, or ; may follow an expr or stmt fragment, and | cannot follow pat; use pat_param when | must be your separator. Read references/declarative-macros.md when you pick a separator after pat, ty, path, or vis; it has the full follow-set table.

error: `$e:expr` is followed by `$s:stmt`, which is not allowed for `expr` fragments
  = note: allowed there are: `=>`, `,` or `;`

Every metavariable in a matcher needs a fragment specifier. ($x) => fails with error: missing fragment specifier in every edition since Rust 1.89.

A parsed fragment is opaque to the next matcher

Once a matcher captures $e:expr, the capture is a single AST node, not tokens. Forwarding it to a macro that expects $i:ident fails even when the caller wrote a bare identifier.

error: no rules expected `expr` metavariable
note: while trying to match meta-variable `$i:ident`

Capture as tt in the outer macro when you must forward to an inner matcher, and parse only at the last step that needs the fragment.

Edition 2024 widened expr

In edition 2024 $e:expr also matches const { 1 + 1 } and the underscore expression _. Edition 2021 rejects the const block with error: no rules expected keyword `const` and the underscore with error: no rules expected reserved identifier `_` . An arm that assumes the capture is a value expression can now receive _, which is not one. Use expr_2021 to keep the edition 2021 match set.

The recursion limit is 128 expansions

A tt-muncher costs one expansion per token. Measured with a counting muncher: 127 input tokens compile, 128 fail with error: recursion limit reached while expanding `count!` . A crate-root #![recursion_limit = "256"] is legitimate for a deliberately recursive macro. Prefer a shape that halves the input per step, because expansion time grows with the count.

A trailing semicolon breaks expression position

The braces around an arm body are delimiters, not a block. () => { 42; } expands to the statement 42;, and let x = val!(); needs an expression. The semicolon_in_expressions_from_macros lint rejects it, deny-by-default since Rust 1.91. That lint fires only when the macro is defined in the crate that invokes it. Up to Rust 1.98.1, an invocation from tests/*.rs or a downstream crate compiles without a warning. Rust 1.99 adds semicolon_in_expressions_from_non_local_macros, warn-by-default and part of future_incompatible, for a macro from another crate. On 1.99.1 a downstream build under -D warnings fails on the defect.

Remove the ; after the last expression. When the body needs statements, add an inner block with double braces: () => {{ let base = 40; base + 2 }}.

Build a format string

A format string must be a literal token: forward the caller's literal with $fmt:literal, or build one with concat!. A format string from concat! cannot capture variables inline. The $(,)? tail accepts an optional trailing comma; add it to every repetition that a caller writes across several lines. Read references/declarative-macros.md when a macro builds or forwards a format string.

Procedural macro crates

A procedural macro lives in its own crate:

[lib]
proc-macro = true

[dependencies]
proc-macro2 = "1"
quote = "1"
syn = "3"

The crate exports macro functions and nothing else, and it cannot invoke its own macros. Neither error carries an error[Ennnn] code or names the proc-macro = true key.

Keep the #[proc_macro_derive] function thin. Parse with syn::parse_macro_input!, put the logic in fn expand(input: DeriveInput) -> syn::Result<proc_macro2::TokenStream>, and map an error with .unwrap_or_else(syn::Error::into_compile_error). The user then sees a normal diagnostic on the span you chose.

Read references/derive-macro-crates.md when you write a derive or set up the facade and derive pair: skeleton, dependency direction, generic bounds, and the missing-derive error.

Pick the syn major

syn 3 is current (3.0.0 on 2026-07-18). As of 2026-09, serde_derive, thiserror-impl, tokio-macros, and clap_derive require syn ^3, while other popular macro crates still use syn 2. Each major in the tree is a separate build of a large crate.

cargo tree --locked -e normal,build -i syn

One version prints its dependents. Two majors print error: specification `syn` is ambiguous and list both. Run cargo tree --locked -e normal,build -i syn@2 to list the dependencies that still build syn 2. Use the major the tree already builds. When the tree has both or none, use syn = "3". syn-2 code fails on syn 3 with E0599, E0609, or E0432 on renamed items such as Type::BareFn, Signature::unsafety, and Arm::guard. Read references/syn-3.md when you port a macro crate or fix those errors.

Related skills

Use these skills by name when they are installed.