Welcome

Welcome to our Rust procedural macros course!
You’ll learn how to extend the Rust compiler by writing your own procedural macros.

Procedural macros allow you to run code at compile time that operates over Rust syntax, both consuming and producing Rust syntax. You can sort of think of procedural macros as functions from an AST to another AST.

The Rust Reference

I’ll take you on a journey through the Rust macro system, exploring derive macros, attribute macros, and function-like macros, learning how to parse and generate Rust code using the syn and quote crates.

Methodology

This course is based on the “learn by doing” principle.
It has been designed to be interactive and hands-on.

Mainmatter developed this course to be delivered in a classroom setting, in a single day: each attendee advances through the lessons at their own pace, with an experienced instructor providing guidance, answering questions and diving deeper into the topics as needed.
If you’re interested in attending one of our training sessions, or if you’d like to bring this course to your company, please get in touch.

You can also follow the course on your own, but we recommend you find a friend or a mentor to help you along the way should you get stuck. You can also find solutions to all exercises in the solutions branch of the GitHub repository.

Structure

On the left side of the screen, you can see that the course is divided into sections. Each section introduces a new concept or feature.
To verify your understanding, each section is paired with an exercise that you need to solve.

You can find the exercises in the companion GitHub repository.
Before starting the course, make sure to clone the repository to your local machine:

# If you have an SSH key set up with GitHub
git clone git@github.com:mainmatter/rust-proc-macro-workshop.git
# Otherwise, use the HTTPS URL:
#
#   git clone https://github.com/mainmatter/rust-proc-macro-workshop.git

We also recommend you work on a branch, so you can easily track your progress and pull in updates from the main repository, if needed:

cd rust-proc-macro-workshop
git checkout -b my-solutions

All exercises are located in the exercises folder. Each exercise is a Rust package, and most are split into two crates: a thin consumer crate and a procedural-macro sub-crate (named after the exercise, e.g. struct-fields-exercise-macros) that holds the macro you’ll be working on. The instructions on what to do, along with a test suite to automatically verify your solution, live next to the code you need to edit: usually in the macro sub-crate’s src/lib.rs, or in src/lib.rs for the simpler single-crate exercises.

`wr`, the workshop runner

To verify your solutions, we’ve also provided a tool to guide you through the course: the wr CLI, short for “workshop runner”. Install wr by following the instructions on its website.

Once you have wr installed, open a new terminal and navigate to the top-level folder of the repository. Run the wr command to start the course:

wr

wr will verify the solution to the current exercise.
Don’t move on to the next section until you’ve solved the exercise for the current one.

You can also check a specific exercise without advancing through the course: navigate into its folder and run wr check.

cd exercises/01_intro/00_welcome/
wr check

We recommend committing your solutions to Git as you progress through the course, so you can easily track your progress and “restart” from a known point if needed.

A note on AI assistants

We strongly recommend that you disable AI coding assistants (agents, copilots, autocomplete suggestions) while working through the exercises.
The goal of this course is to learn by doing: struggling with the code, reading the documentation, and building your own mental model of how procedural macros work. Letting an AI fill in the blanks for you would short-circuit the learning process.

Enjoy the course!

Rust procedural macros workshop

Welcome

Methodology

Structure

`wr`, the workshop runner

A note on AI assistants

Author

License

Exercise

Keyboard shortcuts

Rust procedural macros workshop