Repolode
Submit
dtolnay

dtolnay/proc-macro-workshop

A hands-on workshop of five Rust procedural macro projects, each with a skeleton and a trybuild test suite to implement.

View on GitHub
Stars
4,874
Forks
1,218
Open issues
3
Last commit
3 months ago

What is it?

This repository is a learning workshop for writing Rust procedural macros, which are Rust functions that generate Rust code at compile time. It contains five projects: a derive macro for the builder pattern, a customizable Debug derive that accepts format strings per field, a function-like macro seq! that stamps out indexed copies of code, an attribute macro #[sorted] that reports unsorted enum variants as compile errors, and a #[bitfield] attribute that packs struct fields into a byte array with generated getters and setters.

Each project ships as a skeleton with a test suite under its tests directory. Tests are run with trybuild, which checks both successful expansions and the exact compiler error messages for code that should fail to compile. The workshop suggests a progression, starting with derive(Builder) and then choosing among the other projects depending on whether you want to focus on trait bounds, custom input parsing, or diagnostics.

The repository also explains debugging techniques for macros, such as using cargo expand and printing generated token streams to stderr.

Key features

  • 01Five graded projects covering derive, function-like, and attribute macros.
  • 02Test suites built on trybuild that check exact compiler error output.
  • 03Skeleton code and step-by-step test enablement for each project.
  • 04Debugging guidance using cargo expand and token stream printing.
  • 05Suggested learning order based on your interests.

Use cases

  • Learning Rust procedural macros for the first time with guided exercises.
  • Practicing trait bound handling in generic derive macros.
  • Preparing to write custom compile-time diagnostics for a Rust library.
  • Studying how a bit-packed struct API can be generated from a macro.

Quick start

  1. 1

    Clone the repository and enter a project directory such as builder

  2. 2

    Run the test suite for that project

    cargo test

Topics

#rust#procedural-macros#metaprogramming#learning#workshop#trybuild#code-generation

FAQ

What is proc-macro-workshop?
A hands-on workshop of five Rust procedural macro projects, each with a skeleton and a trybuild test suite to implement. This repository is a learning workshop for writing Rust procedural macros, which are Rust functions that generate Rust code at compile time. It contains five projects: a derive macro for the builder pattern, a customizable Debug derive that accepts format strings per field, a function-like macro seq! that stamps out indexed copies of code, an attribute macro #[sorted] that reports unsorted enum variants as compile errors, and a #[bitfield] attribute that packs struct fields into a byte array with generated getters and setters.
Is proc-macro-workshop free to use? What license does it have?
proc-macro-workshop is open source under the Apache-2.0 license. Check the license terms before using it in commercial products.
Is proc-macro-workshop still maintained?
Updated within 6 months. The last commit to proc-macro-workshop was on Aug 6, 2026.
What can I use proc-macro-workshop for?
Learning Rust procedural macros for the first time with guided exercises. Practicing trait bound handling in generic derive macros. Preparing to write custom compile-time diagnostics for a Rust library. Studying how a bit-packed struct API can be generated from a macro.
How do I install proc-macro-workshop?
Clone the repository and enter a project directory such as builder Run the test suite for that project: cargo test
Where can I get proc-macro-workshop?
The source code and installation instructions are on GitHub: https://github.com/dtolnay/proc-macro-workshop

Summary generated by AI from the project's README. GitHub stats refresh daily.

Related projects