24. Rust Declarative and Procedural Macros

Rust macros generate syntax that is subsequently checked as Rust code; they are not runtime functions with unusual punctuation. This lesson builds a small local workspace to demonstrate macro_rules! and all three procedural macro forms without fetching dependencies.

Learning goals and prerequisites

You should be comfortable with crates and visibility, traits and testing. Pinning from lesson 23 is not needed by the program; this is another language mechanism, not an extension of an async runtime.

By the end, identify matched fragments and repeated expansion, check that expressions are evaluated as intended, and distinguish adding items with derive from replacing an attributed item. Use stable Rust, Cargo and edition 2024. No sensor access, installed macro tools or external crates are required.

Rust macro_rules: syntax first, types later

Our list macro has one arm for no arguments and one for comma-separated expressions. $value:expr matches an expression, not a runtime i32 value. Repetition with + requires at least one expression; $(,)? permits one trailing comma. The transcriber repeats one push per matched expression, using an extra block so the expansion is a single expression.

The second macro simply calls a normal function through $crate. It is deliberately unnecessary for this calculation: an ordinary function is the better default when no syntax generation is needed. Compare the fragment and repetition rules in the macros-by-example Reference.

Create the six-file workspace

Create a fresh directory with the following files. The root is a library/binary package; fixture-macros is a separate compiler plugin package with proc-macro = true. A Cargo workspace coordinates their builds and lockfile, while the path dependency makes the plugin available to the root package. No registry package is needed.

mkdir -p rust-macros/src rust-macros/tests rust-macros/fixture-macros/src
cd rust-macros
# Create the six files shown below, preserving their paths.
cargo fmt --all --check
cargo check --workspace --offline
cargo test --workspace --offline
cargo test --workspace --release --offline
cargo doc --workspace --no-deps --offline
cargo run --quiet --offline

Cargo.toml

[package]
name = "rust_macros"
version = "0.1.0"
edition = "2024"

[workspace]
members = ["fixture-macros"]
resolver = "3"

[dependencies]
fixture_macros = { path = "fixture-macros" }

fixture-macros/Cargo.toml

[package]
name = "fixture_macros"
version = "0.1.0"
edition = "2024"

[lib]
proc-macro = true

src/lib.rs

pub trait FixtureName {
    fn fixture_name() -> &'static str;
}

/// Accept a fixture reading within this example's declared range.
/// This is a teaching policy, not a hardware specification.
pub fn checked_reading(value: i32) -> Option<i32> {
    (-100_000..=150_000).contains(&value).then_some(value)
}

#[macro_export]
macro_rules! readings {
    () => {
        ::std::vec::Vec::new()
    };
    ($($value:expr),+ $(,)?) => {{
        let mut values = ::std::vec::Vec::new();
        $(values.push($value);)+
        values
    }};
}

#[macro_export]
macro_rules! bounded_reading {
    ($value:expr) => {
        $crate::checked_reading($value)
    };
}

#[cfg(test)]
mod tests {
    #[test]
    fn empty_input_has_an_explicit_element_type() {
        let values: Vec<i32> = crate::readings!();
        assert!(values.is_empty());
    }

    #[test]
    fn trailing_comma_and_zero_are_preserved() {
        assert_eq!(crate::readings!(46_700, 0, -500,), [46_700, 0, -500]);
    }

    #[test]
    fn expressions_run_once_in_list_order() {
        let mut calls = 0;
        let values = crate::readings!(
            {
                calls += 1;
                calls
            },
            {
                calls += 1;
                calls
            },
        );
        assert_eq!(values, [1, 2]);
        assert_eq!(calls, 2);
    }

    #[test]
    fn expanded_local_does_not_replace_callers_binding() {
        let values = "caller";
        let generated = crate::readings!(0);
        assert_eq!(values, "caller");
        assert_eq!(generated, [0]);
    }

    #[test]
    fn function_still_enforces_range_policy() {
        assert_eq!(crate::bounded_reading!(-100_000), Some(-100_000));
        assert_eq!(crate::bounded_reading!(150_000), Some(150_000));
        assert_eq!(crate::bounded_reading!(150_001), None);
    }
}

fixture-macros/src/lib.rs

use proc_macro::{TokenStream, TokenTree};

// This derive intentionally accepts only: struct Name;
#[proc_macro_derive(FixtureName)]
pub fn fixture_name(input: TokenStream) -> TokenStream {
    let tokens: Vec<_> = input.into_iter().collect();
    match tokens.as_slice() {
        [
            TokenTree::Ident(keyword),
            TokenTree::Ident(name),
            TokenTree::Punct(end),
        ] if keyword.to_string() == "struct" && end.as_char() == ';' => format!(
            "impl FixtureName for {name} {{
                    fn fixture_name() -> &'static str {{ stringify!({name}) }}
                }}"
        )
        .parse()
        .expect("fixed implementation syntax"),
        _ => "compile_error!(\"FixtureName accepts only a private unit struct\");"
            .parse()
            .expect("fixed diagnostic syntax"),
    }
}

// Attribute output replaces the input item, so retain that item explicitly.
#[proc_macro_attribute]
pub fn add_debug(arguments: TokenStream, item: TokenStream) -> TokenStream {
    if !arguments.is_empty() {
        return "compile_error!(\"add_debug takes no arguments\");"
            .parse()
            .expect("fixed diagnostic syntax");
    }
    let mut output: TokenStream = "#[derive(Debug)]".parse().expect("fixed attribute syntax");
    output.extend(item);
    output
}

#[proc_macro]
pub fn fixture_value(input: TokenStream) -> TokenStream {
    if input.is_empty() {
        "46_700i32".parse().expect("fixed expression syntax")
    } else {
        "compile_error!(\"fixture_value takes no arguments\")"
            .parse()
            .expect("fixed diagnostic syntax")
    }
}

src/main.rs

use fixture_macros::{FixtureName, add_debug, fixture_value};
use rust_macros as renamed;
use rust_macros::FixtureName;

#[derive(FixtureName)]
struct Pi;

#[add_debug]
struct Status {
    reading: i32,
}

fn main() {
    let values = renamed::readings!(fixture_value!(), 0, -500,);
    println!("readings={values:?}");
    println!("checked={:?}", renamed::bounded_reading!(0));
    println!("name={}", Pi::fixture_name());
    let status = Status {
        reading: fixture_value!(),
    };
    assert_eq!(status.reading, 46_700);
    println!("debug={status:?}");
}

tests/public_macros.rs

use fixture_macros::{FixtureName, add_debug, fixture_value};
use rust_macros as renamed;
use rust_macros::FixtureName;

#[derive(FixtureName)]
struct Probe;

#[add_debug]
struct State;

#[test]
fn crate_path_survives_caller_alias_and_shadowed_helper() {
    fn checked_reading(_: i32) -> Option<i32> {
        None
    }
    assert_eq!(checked_reading(0), None);
    assert_eq!(renamed::bounded_reading!(0), Some(0));
}

#[test]
fn derive_adds_an_implementation_without_removing_type() {
    let _original_type_still_exists = Probe;
    assert_eq!(Probe::fixture_name(), "Probe");
}

#[test]
fn attribute_retains_item_and_function_macro_emits_typed_expression() {
    assert_eq!(format!("{:?}", State), "State");
    let value: i32 = fixture_value!();
    assert_eq!(value, 46_700);
}

Expected output:

readings=[46700, 0, -500]
checked=Some(0)
name=Pi
debug=Status { reading: 46700 }

Read the expansion before assuming its behaviour

The tests are part of this macro's contract: empty input needs an element type, zero is retained, arguments are evaluated once and in order, and its temporary values binding does not overwrite the caller's values. Macro code could instead duplicate an expression or ignore it; a macro invocation does not inherently guarantee ordinary function-style argument evaluation. The Book's macro introduction provides a useful comparison with functions.

readings! exports at the crate root. $crate in bounded_reading! refers to the defining library, even when its caller uses a different imported name or defines its own checked_reading. It does not bypass visibility: our helper must still be public for callers outside the library. Declarative macros have mixed-site hygiene, not automatic protection for every referenced name. Consult the hygiene rules when expanding references to other items.

Three procedural macro interfaces

The procedural macro Reference distinguishes function-like expansion, derive-generated additional items and attribute-generated replacement items. All run during compilation in another crate. Our derive's output is an impl, not a replacement struct. add_debug keeps the item token stream and prefixes another attribute; fixture_value produces an expression.

The compiler-provided TokenTree API represents groups, identifiers, punctuation and literals. Our derive examines three top-level tokens. It intentionally rejects public structs, fields, generics, enums, unions and additional attributes. This is a tiny specified input language, not a general Rust parser. Printing arbitrary token streams as strings and reparsing is not a robust substitute for parsing full Rust syntax; preserve spans and input tokens when building production diagnostics.

The generated FixtureName path resolves at the caller. That is why both consumer files import the trait, as well as the derive macro with the same name in the macro namespace. Procedural macro output is not hygienically isolated from caller names. A production derive needs a considered path-resolution strategy and input parser; our limited example advertises neither.

Compile-time code has a trust boundary

These macros do not read files, contact a network or inspect the Pi. A third-party procedural macro or build script can run code with the compiler process's resources during a build. Treat dependency selection as a trust decision; generated code must also obey ordinary typing, ownership and privacy. In cross-compilation, a procedural macro executes on the build host rather than becoming Pi runtime code. Building natively here verifies the examples on the Pi, not a cross-compilation setup.

Deliberately failing: generated calls remain type-checked

In a separate copy of this workspace, replace only src/main.rs with:

fn main() {
    let _value = rust_macros::bounded_reading!("46700");
}

cargo check reports E0308: our function expects i32, not str. Matching an expr is not permission to pass any type to the emitted function. Repair the argument as 46_700, or explicitly parse text through a Result-returning API if text is the intended input.

Exercises and troubleshooting

1. Repair the type failure and add an assertion for Some(46700). Do not hide parsing failure behind a fabricated zero.
2. Add more side-effecting expressions to readings!. Predict their values and the final call counter before running the tests.
3. Remove the optional trailing comma matcher and retain the existing calls. Expect a macro-matching error. Repair either the grammar or the invocations deliberately.
4. Make checked_reading private while retaining its exported macro and binary caller. Expect E0603: $crate repairs resolution, not visibility.
5. Apply FixtureName to a named-field or generic struct. Expect our explicit input-restriction diagnostic, not a guessed implementation. Extend a parser only if you are prepared to support those shapes and test them.
6. Call fixture_value!(123), and separately apply #[add_debug(extra)]. Both must reject arguments instead of silently ignoring user input.
7. Remove the trait import from a derive consumer. Expect E0404 for the generated impl: a derive macro with that name exists in another namespace, but the trait is absent. Explain the limitation instead of claiming that a proc-macro crate automatically imports its trait.
8. Prefer a normal function for the range policy. Identify why syntax repetition and generated implementations, unlike that policy, actually need macro machinery.

Verification and next step

On October 10, 2026, the six-file workspace was verified on the authorised Raspberry Pi 4B with 64-bit user space, kernel 6.18.50+rpt-rpi-v8, Rust and Cargo 1.99.0, and edition 2024. Workspace checks, five library tests and three integration tests in debug/release, formatting, documentation and debug/release output comparisons passed, as did the integer-argument repair. Eight compiler failures verified type checking, private helpers, trailing-comma matching, named-field/generic derive rejection, unexpected function/attribute arguments and a missing trait import. The fixture macros intentionally remain limited; this lesson makes no claim to implement a production derive library.

Continue with attributes, cfg, features and editions: identify which code is compiled and test each feature configuration.

Previous: Pin and Unpin · Course overview