How to write a custom derive macro?

rust rust-macros

11,679

Create a crate for your procedural macros:
```
 cargo new my_derive --lib
```
Edit the Cargo.toml to make it a procedural macro crate:
```
 [lib]
 proc-macro = true
```

Implement your procedural macro:

 extern crate proc_macro;

 use proc_macro::TokenStream;

 #[proc_macro_derive(MyMacroHere)]
 pub fn my_macro_here_derive(input: TokenStream) -> TokenStream { 
     // ...
 }

Import the procedural macro and use it:

 extern crate my_derive;

 use my_derive::MyMacroHere;

 #[derive(MyMacroHere)]
 struct Example {
     id: i64,
     value: Option<String>,
 }

The hard part is in implementation of the macro. Most people use the syn and quote crates to parse the incoming Rust code and then generate new code.

For example, syn's documentation starts with an example of a custom derive. You will parse the struct (or enum or union) and then handle the various ways of defining a struct (unit, tuple, named fields). You'll collect the information you need (type, maybe name), then you'll generate the appropriate code.

Lev

Updated on June 12, 2022

Comments

Lev almost 2 years
I'm trying to write my own derive mode macro in Rust, and the documentation on it is somewhat lacking in examples.

I have a struct like:
```
#[derive(MyMacroHere)]
struct Example {
    id: i64,
    value: Option<String>,
}
```
I want my macro to generate a method à la
```
fn set_fields(&mut self, id: i64, value: Option<String>) {
    // ...
}
```
What are the basic steps to use the TokenStream trait to achieve something like that?
- Joe Clay over 5 years
  
  The reference probably isn't the best place to go for documentation on procedural macros - have you read the 'Macros' appendix from the Rust book and the API docs for the proc_macro built-in library? They'd be the best places to start, in my opinion.
- Joe Clay over 5 years
  
  The general gist of how procedural macros work is that they take in a TokenStream (in this case, it'd be the tokens that make up the definition of Example), and then run a piece of code that generates a new TokenStream to add to the program (this would be the tokens that make up the set_fields definition). People generally use the syn crate to translate the input tokens to a proper Rust syntax tree, and the quote crate to generate the output.
ehdv over 5 years

To make parsing easier, I've built darling. It exposes a serde-like API where you define a struct for the arguments your macro needs, and then pass it a syn::DeriveInput. It handles parsing, field validation, duplicate field checking, and error creation.