Macros on

Lesson 12: Macro Anti-Patterns — When not to macro

Tue, 04 Mar 2025 12:50:00 +0000

I once worked on a codebase where someone had written a macro for everything. Creating structs? Macro. Implementing a two-line function? Macro. Logging? Custom logging macro that wrapped println! and added a timestamp. The macro definitions file was 800 lines long. The macros had macros inside them. Nobody on the team could modify them without breaking something, and the original author had left six months earlier. That project taught me more about when not to use macros than any tutorial ever could.

Lesson 11: Real-World Macro Patterns — serde, clap, sqlx under the hood

Sat, 01 Mar 2025 15:40:00 +0000

I used #[derive(Serialize)] for two years before I actually looked at what it generates. When I finally ran cargo expand on a struct with five fields, I got 150 lines of serialization code — visitor patterns, generic bounds, field-by-field traversal, error handling. All generated from a single line. Understanding how production crates use macros changed how I think about API design. These aren’t academic exercises — they’re the patterns behind the most downloaded crates in the ecosystem.

Lesson 10: syn and quote — Parsing and generating tokens

Thu, 27 Feb 2025 10:20:00 +0000

Every time I write a proc macro without syn and quote, I regret it within twenty minutes. Raw TokenStream manipulation is like writing HTML by concatenating strings — technically possible, practically unbearable. These two crates are the reason Rust’s proc macro ecosystem works at all. They handle the two hardest parts — parsing Rust syntax into a usable data structure, and generating valid Rust code from a template — so you can focus on the actual logic of your macro.

Lesson 9: Function-Like Proc Macros — sql!() and friends

Mon, 24 Feb 2025 18:30:00 +0000

A colleague once asked me why sqlx::query!("SELECT * FROM users WHERE id = $1") can catch SQL errors at compile time. “Is it reading the database during compilation?” Yes. It literally connects to your database, validates the query, checks the types, and generates type-safe Rust code — all before your program runs. That’s a function-like proc macro doing things that feel illegal. And the mechanics behind it are more straightforward than you’d think.

Lesson 8: Attribute Macros — #[my_attr] in practice

Sat, 22 Feb 2025 07:15:00 +0000

I was reviewing a codebase that used Actix Web and kept seeing #[get("/users")] on handler functions. I knew it was a macro, but I didn’t understand the mechanics — how does an attribute on a function transform the function? Where does the routing registration happen? When I finally built my own attribute macro, the whole system clicked. Attribute macros aren’t magic. They’re just functions that receive code and return different code.

Lesson 7: Derive Macros — Custom #[derive()]

Wed, 19 Feb 2025 13:55:00 +0000

The first derive macro I shipped to production generated about 200 lines of boilerplate per struct. We had 47 structs. That’s 9,400 lines of code I didn’t have to write, test, or maintain. Every time someone added a field to a struct, the derive macro picked it up automatically. No manual updates, no forgotten implementations, no “oh I changed the struct but forgot to update the builder” bugs. Derive macros are the highest-leverage tool in Rust’s macro system, and once you build one, you’ll find excuses to build more.

Lesson 6: Procedural Macros — The three kinds

Mon, 17 Feb 2025 09:40:00 +0000

The moment I realized macro_rules! couldn’t generate new identifier names from captured inputs, I knew I needed something more powerful. I was trying to auto-generate a _builder suffix for struct names — take Config and produce ConfigBuilder. Declarative macros can’t do string manipulation on identifiers. Period. That’s what pushed me into procedural macros, and honestly, it felt like unlocking a completely different layer of the language.

What Procedural Macros Actually Are

A procedural macro is a Rust function that runs at compile time. It receives a stream of tokens as input, does whatever processing it wants — parsing, analyzing, transforming — and returns a new stream of tokens as output. The compiler then compiles the returned tokens as if they were regular source code.

Lesson 5: Debugging Macros — cargo-expand and trace_macros

Fri, 14 Feb 2025 11:05:00 +0000

You will write a macro that compiles, runs, and produces the wrong output. You’ll stare at the macro definition, convinced it’s correct. You’ll re-read the pattern matching rules, check the repetition operators, verify the fragment specifiers — everything looks right. And then you’ll expand the macro and realize it’s generating something completely different from what you imagined. This has happened to me more times than I’m willing to admit.

Macro debugging is a different skill from regular debugging. You can’t set breakpoints in macro expansion. You can’t step through it. You have to see the generated code, and then reason backwards from there to figure out where the pattern matching went wrong.

Lesson 4: Macro Hygiene — Scoping and naming pitfalls

Wed, 12 Feb 2025 16:10:00 +0000

I once spent an embarrassing amount of time debugging a macro that worked perfectly in one file and broke in another. Same macro, same input, different behavior. Turned out the expansion was referencing a variable called result — which happened to shadow a result variable at the call site. The macro was hygienically correct in isolation but collided with the caller’s namespace. That’s when I actually understood what “macro hygiene” means and why Rust only gets it partially right.

Lesson 3: Macro Pattern Matching — Repetition, fragments, and captures

Mon, 10 Feb 2025 08:30:00 +0000

There’s a point when writing declarative macros where the syntax stops feeling like Rust and starts feeling like regex for code. You’re stacking repetition operators, nesting captures inside captures, and using tt munching to parse things the macro system was never designed to parse. It’s weird, it’s powerful, and once it clicks, you’ll wonder why you ever wrote boilerplate by hand.

Repetition Operators Deep Dive

We touched on repetition in the last lesson. Now let’s get into the mechanics that actually matter when you’re building non-trivial macros.

Lesson 2: Declarative Macros — macro_rules! from zero

Fri, 07 Feb 2025 14:45:00 +0000

The first macro I ever wrote was a disaster. I wanted a shorthand for creating HashMaps — something like map!{ "a" => 1, "b" => 2 }. The macro compiled. The expansion was garbage. I didn’t understand fragment specifiers, I didn’t understand repetition, and I definitely didn’t understand why the compiler kept telling me “unexpected token.” Took me a full weekend to get it right. Let me save you that weekend.

Lesson 1: Why Macros — When functions aren't enough

Wed, 05 Feb 2025 10:22:00 +0000

I spent three hours once writing nearly identical impl blocks for sixteen different numeric types. Copy, paste, change i32 to i64, change i64 to u32, repeat. Halfway through I started making typos. By the end I had a bug in the u128 variant that took another hour to find. That’s the day I actually sat down and learned macros properly.

The Gap Between Functions and Macros

Functions are great. You take some inputs, do some work, return a result. But functions operate on values. They can’t generate new struct definitions. They can’t implement traits for you. They can’t vary the number or types of arguments they accept. They can’t produce different code depending on what you pass them at compile time.