Nivel 3 · Sistemas· Lección 6 de 11 · 30 min
Macros procedurales
Macros derive, de atributo y de tipo función — programas de Rust que se ejecutan dentro del compilador y escriben Rust.
Tres clases
| Clase | Aspecto | Entrada | Salida |
|---|---|---|---|
| Derive | #[derive(Serialize)] |
el struct/enum | se añade junto a él |
| Atributo | #[tokio::main], #[test] |
los argumentos del atributo + el elemento | sustituye al elemento |
| Tipo función | sqlx::query!("…") |
tokens arbitrarios | sustituye a la invocación |
Cada una es una función de Rust TokenStream -> TokenStream a la que el compilador llama durante la expansión. Puede ejecutar cualquier código: analizar la entrada, leer archivos, incluso hablar con una base de datos (como hace sqlx para comprobar los tipos del SQL). Ese poder es la razón por la que hay que usarlas con mesura: cuestan tiempo de compilación y pueden ocultar muchas cosas.
Estructura del proyecto
builder/
├── Cargo.toml # workspace
├── builder-derive/ # el crate proc-macro
│ ├── Cargo.toml
│ └── src/lib.rs
└── app/ # un crate que lo usa
# builder-derive/Cargo.toml
[lib]
proc-macro = true
[dependencies]
syn = { version = "2", features = ["full"] }
quote = "1"
proc-macro2 = "1"
Una macro derive, paso a paso
Objetivo: #[derive(Builder)] sobre un struct genera un FooBuilder con un método de asignación por campo y un build() que informa del primer campo que falta.
// builder-derive/src/lib.rs
use proc_macro::TokenStream;
use quote::{format_ident, quote};
use syn::{parse_macro_input, Data, DeriveInput, Fields};
#[proc_macro_derive(Builder)]
pub fn derive_builder(input: TokenStream) -> TokenStream {
// 1. Analiza los tokens y construye un árbol sintáctico.
let input = parse_macro_input!(input as DeriveInput);
let name = &input.ident;
let builder = format_ident!("{}Builder", name);
// 2. Extrae lo que necesitamos, y rechaza con un buen error lo que no admitimos.
let Data::Struct(data) = &input.data else {
return syn::Error::new_spanned(name, "Builder can only be derived for structs")
.to_compile_error()
.into();
};
let Fields::Named(fields) = &data.fields else {
return syn::Error::new_spanned(name, "Builder requires named fields")
.to_compile_error()
.into();
};
let idents: Vec<_> = fields.named.iter().map(|f| f.ident.as_ref().unwrap()).collect();
let types: Vec<_> = fields.named.iter().map(|f| &f.ty).collect();
let missing: Vec<_> = idents.iter().map(|i| format!("missing field `{i}`")).collect();
// 3. Genera el código. `#var` interpola; `#( … )*` repite.
let expanded = quote! {
#[derive(Default)]
pub struct #builder {
#( #idents: ::core::option::Option<#types>, )*
}
impl #builder {
#(
pub fn #idents(mut self, value: #types) -> Self {
self.#idents = ::core::option::Option::Some(value);
self
}
)*
pub fn build(self) -> ::core::result::Result<#name, &'static str> {
::core::result::Result::Ok(#name {
#( #idents: self.#idents.ok_or(#missing)?, )*
})
}
}
impl #name {
pub fn builder() -> #builder {
#builder::default()
}
}
};
expanded.into()
}
Para usarla:
// app/src/main.rs
use builder_derive::Builder;
#[derive(Debug, Builder)]
struct Request {
url: String,
retries: u32,
}
fn main() {
let ok = Request::builder().url("https://example.com".into()).retries(3).build();
let bad = Request::builder().retries(3).build();
println!("{ok:?}\n{bad:?}"); // Ok(Request { … }) / Err("missing field `url`")
}
Cosas que importan en la práctica
Spans y errores. Cada token lleva un span: su ubicación en el código fuente. Informa de los problemas con syn::Error::new_spanned(tokens, msg) para que el error subraye el código del usuario, no la macro. Nunca uses panic! ante los errores del usuario.
Higiene. Las macros procedurales no son higiénicas por defecto: los identificadores generados se resuelven en el lugar de la llamada. Usa rutas absolutas (::core::option::Option), porque el usuario puede haber sombreado Option o Result, y prefiere ::core a ::std para que la macro funcione en crates no_std.
Genéricos. Un derive de verdad debe arrastrar los genéricos del struct:
// dentro de un derive, con `input: DeriveInput` y `name = &input.ident`
let (impl_generics, ty_generics, where_clause) = input.generics.split_for_impl();
let expanded = quote! {
impl #impl_generics MyTrait for #name #ty_generics #where_clause {
// …
}
};
Atributos auxiliares. #[proc_macro_derive(Builder, attributes(builder))] permite #[builder(default)] en los campos; se leen desde field.attrs.
Pruebas. Pon la lógica en una función sobre proc_macro2::TokenStream para poder probarla con pruebas unitarias. Usa cargo expand para leer la salida y el crate trybuild para comprobar los errores de compilación.
Tiempo de compilación. syn con todas sus características es una dependencia pesada, y cada invocación ejecuta tu código. Una macro macro_rules! o una función genérica, cuando bastan, son más baratas para todos los que dependen de ti.
Macros de atributo
// en el crate proc-macro
use proc_macro::TokenStream;
use quote::quote;
use syn::{parse_macro_input, ItemFn};
/// Envuelve una función para que imprima cuánto tardó cada llamada.
#[proc_macro_attribute]
pub fn timed(_args: TokenStream, item: TokenStream) -> TokenStream {
let ItemFn { attrs, vis, sig, block } = parse_macro_input!(item as ItemFn);
let name = sig.ident.to_string();
quote! {
#(#attrs)* #vis #sig {
let __start = ::std::time::Instant::now();
let __result = (move || #block)();
eprintln!("{} took {:?}", #name, __start.elapsed());
__result
}
}
.into()
}
Esta es la forma de #[tokio::main], de #[test] y de los atributos de ruta de los frameworks web: recibir un elemento y emitir un elemento transformado.
Ejercicios
- Construye el derive
Builderen un workspace y ejecútalo. Usacargo expandpara leer lo que genera. - Haz que los campos
Option<T>sean opcionales en el builder (por defecto valenNoney el método de asignación recibeT). Tendrás que inspeccionarsyn::Type::Path. - Admite structs genéricos con
split_for_impl. - Añade un atributo de campo
#[builder(default = "expr")]. - Escribe una prueba con
trybuildque compruebe que derivarBuilderen un enum produce tu mensaje de error.
Comprueba lo que has entendido
Elige una respuesta para ver la explicación.
1.¿Por qué las macros procedurales deben vivir en su propio crate con
proc-macro = true?2.¿Qué puede hacer una macro derive con el elemento al que se aplica?
3.¿Qué crates forman el conjunto de herramientas estándar para escribir macros procedurales?