skip to content

After a Rust workspace adopts a `#[route]` attribute macro built on syn with its `full` feature, builds slow down — where does the time go, and how do you cut it?

level: seniorimportance: should knowfreq 35%

answer

  1. on the critical path
  2. a whole syntax tree
  3. built for the host
  4. unoptimised by default
  5. re-run on every compile

basics

~20 s

The time goes to building the macro crate and syn's full syntax tree before any user crate starts, re-running the macro on every compile, and compiling the code it emits. Cut it by parsing less, enabling fewer features and generating less code.

solid answer

~40 s

Several costs add up. First, the proc-macro crate and its dependencies (`proc-macro2`, `quote`, `syn`) must finish compiling before any crate that uses `#[route]` can start, so they sit on the critical path. syn's `full` feature, which `syn::ItemFn` requires, compiles the syntax tree for every Rust item and expression; derive-only parsing needs just the default features. Second, rustc runs the macro on every compile of the calling crate, because stable has no cache for expansions. Third, Cargo builds macros at `opt-level = 0` even in release by default. Finally, the emitted code still has to be type-checked and compiled. Measure with `cargo build --timings` and nightly `-Zmacro-stats`, then cut by parsing only what you need, trimming the generated code, and moving shared logic into ordinary generic functions the expansion calls.

code

plaintext · 12 lines
plaintext
$ cargo tree -p app -e features -i syn
syn v2.0.119
├── syn feature "default"
│   └── webmac v0.1.0 (proc-macro)
│       └── webmac feature "default"
│           └── app v0.1.0
├── syn feature "derive"
│   └── syn feature "default" (*)
├── syn feature "full"
│   └── webmac v0.1.0 (proc-macro) (*)
└── syn feature "parsing"
    └── syn feature "default" (*)

go deeper

for a junior

Recall that a procedural macro is a separate program the compiler must build and then run, so adding one makes builds slower.

for a middle

Explain syn's feature split, why derive-only parsing is cheaper than full, and why every crate using the macro waits for the macro crate to build.

for a senior

Measure with --timings, cargo tree -e features and nightly macro stats, then cut parsing, generated code and duplicate host builds where they actually show up.

for a principal

Treat build time as a budget the whole team pays on every edit, and require a measured case before a macro joins a core crate's dependency chain.

## Where the time goes A procedural macro is a **program the compiler runs**, so it costs time twice: once to build it and again every time it runs. Then the code it emits has to be compiled like any other code. The next two sections take those costs in turn. ## Building the macro - **The critical path.** A crate that uses `#[route]` cannot start compiling until the proc-macro crate and everything it depends on are built. `proc-macro2`, `quote` and `syn` usually dominate that chain. Parallel builds hide independent crates, but not this chain. - **syn's features.** syn's documentation says it "puts a lot of functionality behind optional features in order to optimize compile time." The defaults are `derive`, `parsing`, `printing`, `clone-impls` and `proc-macro`. With `derive` alone you get `DeriveInput`, which covers what a derive macro needs. Types such as `syn::ItemFn` and `syn::Item` exist only with **`full`**, which compiles the syntax tree for all Rust items and expressions. An attribute macro on functions tends to pull in `full`. - **Feature unification.** Cargo unifies features. If any proc-macro crate in the build enables `full`, every proc-macro crate that shares that syn gets it. `cargo tree -e features -i syn` shows which crate turned it on. - **Built for the host, sometimes twice.** The Reference says proc-macro crates are always compiled for the compiler's own target. When you cross-compile with `--target`, Cargo builds macros and their dependencies separately for the host. Separately from that, Cargo's resolver does not unify features enabled for proc-macro dependencies with the same crate used as a normal dependency. So a crate needed by both, with different features, can be compiled twice. ## Running the macro - **Unoptimised by default.** Cargo's default `build-override` profile builds build scripts, proc macros and their dependencies at `opt-level = 0`, in release as well as dev. A macro that parses large handler bodies runs as debug code. Raising `opt-level` for build dependencies is a Cargo profile setting that trades a slower macro build for faster expansion. - **No caching of the expansion.** rustc runs every invocation again each time it compiles the calling crate, including incremental rebuilds after a one-line edit. Caching derive-macro output exists only as the nightly `-Zcache-proc-macros` option, which its own help text marks as potentially unsound. - **The emitted code.** Every token the macro outputs goes through name resolution, type checking, borrow checking and code generation. A macro that generates large glue code for each handler can cost more downstream than the macro itself costs to run. ## Measuring before changing anything 1. `cargo build --timings` writes an HTML report of every compiler invocation over time. Look for `syn` and the proc-macro crate on the critical path. 2. `cargo tree -e features -i syn` lists the features each dependent enables on syn. 3. On nightly only, `-Zmacro-stats` prints, per macro, how many uses it had and how many lines and bytes it generated. `-Zunpretty=expanded`, or the third-party `cargo expand`, shows the generated code itself. | Symptom | Likely cause | First fix | |---|---|---| | syn high in `--timings` | `full` enabled somewhere | parse less, or find who enables it | | slow incremental edits in macro-heavy files | expansion re-run each compile | fewer or smaller invocations | | long type-check of the user crate | bulky generated code | move logic into generic functions | | the same crate built twice in `--timings` | used by a macro and at run time with different features, or two syn majors | align versions and features | ## Cutting the cost - **Parse only what you use.** A `#[route]` that needs the function's name can read the visibility, `fn` and name, then pass the rest through as an opaque `proc_macro2::TokenStream`, instead of parsing the whole body as an `ItemFn`. That changes run time per invocation. Dropping `full` is possible only if no other macro in the build enables it. - **Generate thin code.** Expand to a call into an ordinary library function, for example `Router::register(METHOD, PATH, handler)`, instead of writing that function's body out at each handler. The generic code is compiled once per instantiation, not re-emitted per call site. - **Prefer `macro_rules!` where it is enough.** A declarative macro adds no extra crate to build. - **Share one syn.** Keep the workspace on one major version of syn, so it is compiled once rather than once per major.

  • Does removing `full` from your own proc-macro crate always remove it from the build?
    No. Cargo unifies features across a dependency, so if any other proc-macro crate in the graph enables syn's `full`, every user of that syn gets it. `cargo tree -e features -i syn` shows who enables it. Dropping it from your crate only helps once nothing else in the build needs it.
  • Why can a release build expand a heavy macro more slowly than you expect?
    By default Cargo builds build dependencies, including proc macros and syn, at `opt-level = 0` in every profile, so the macro runs unoptimised even in a `--release` build. Raising the build-override `opt-level` makes expansion faster but makes the macro crate itself slower to compile. It pays off only when expansion, not building the macro, dominates.

  • A proc macro costs build time once; incremental builds reuse its expansion
  • Release builds compile proc macros with full optimisation by default
  • syn's default features already include the types for parsing whole function bodies
  • Generated code is free, because the macro already ran
  • Cross-compiling builds proc macros for the target device