A few years ago, I was working on a large-scale telemetry system where we had dozens of different event structs. Every single one of them needed to be converted into a specific internal log format. At first, I just implemented a trait for each one manually. Then I got lazy and wrote a declarative macro (macro_rules!) to handle it. But as the requirements grew—like needing to skip certain fields based on a custom attribute—the declarative macro became a nightmare of recursive patterns and confusing syntax. I spent an entire afternoon staring at a compiler error that basically said "something went wrong in the macro expansion," but didn't tell me where.

That was the moment I realized I needed procedural macros. Unlike declarative macros, which are essentially sophisticated find-and-replace tools, procedural macros are actual Rust functions that run during compilation. They take a stream of tokens as input, manipulate them using a full programming language, and spit out a new stream of tokens. It's essentially writing a program that writes your program.

Automating Boilerplate with Custom Derives

The most common procedural macro you've likely already used is the derive macro. When you write #[derive(Debug)], you're telling the compiler to find the Debug derive macro and run it on your struct. As a developer, you can write your own to eliminate repetitive impl blocks.

A derive macro is additive. It doesn't change the struct it's attached to; it just generates additional code (usually a trait implementation) alongside it. For example, imagine you have a Validate trait. Instead of manually writing the validation logic for every single DTO in your API, you can create a #[derive(Validate)] macro. The macro reads the fields of your struct and generates the impl Validate for MyStruct { ... } block automatically. I usually prefer these for 90% of my automation because they are the least intrusive and the easiest for other teammates to understand.

Rewriting Logic via Attribute Macros

Attribute macros are a bit more powerful—and a bit more dangerous. While a derive macro only adds code, an attribute macro can actually transform the item it's attached to. It takes the token stream of the function or struct it's decorating and can return an entirely different token stream, effectively replacing the original code.

You've seen this in action with #[tokio::main]. That attribute isn't just adding something to your main function; it's wrapping your entire function body inside an async runtime initialization block. I use attribute macros when I need to implement "aspect-oriented" programming, like adding a #[log_execution_time] attribute to a function that automatically inserts timing logic at the start and end of the method body without cluttering the business logic.

Flexible Syntax with Function-like Macros

Finally, we have function-like macros. These look and feel like println! or vec!. They are called with an exclamation mark and can take almost any syntax you can imagine as their input. They aren't attached to a specific item; they are invoked wherever you need them in your code.

I find these incredibly useful for creating Domain Specific Languages (DSLs). If you're building a tool that requires a complex configuration tree or a custom routing table for a web server, a function-like macro allows you to define a syntax that is much more readable than nested function calls. Just be careful: because they can take arbitrary tokens, they can be harder to debug if you don't provide clear error messages using the proc_macro_error crate.

📋 Practical Task

Building a Custom Loggable Derive Macro

Your task is to create a procedural macro crate that implements a Loggable trait for any struct it is applied to. This is a classic real-world use case for reducing boilerplate when debugging complex data structures.

Requirements:

• Create a new library crate with proc-macro = true in its Cargo.toml.
• Define a trait named Loggable with a method log_info(&self) that prints the name of the struct.
• Implement a derive macro #[derive(Loggable)].
• The macro should identify the name of the struct it is attached to and generate an implementation of Loggable that prints: "Logging info for struct [StructName]".
• Test the macro by applying it to two different structs (e.g., User and Order) and calling log_info() on them.

Hint: You will need to add syn and quote to your dependencies to parse the token stream and turn it back into Rust code.