proc-macro-error2

proc-macro-error2 makes error reporting in procedural macros simple and easy to use. It is a maintained fork of the original proc-macro-error, updated to work with syn 2, and lets macro authors migrate away from panic!-based errors with minimal effort while producing clear, span-attached diagnostics.

The crate is a tiny shim around proc_macro::Diagnostic and compile_error! that detects the most capable error-emission mechanism available for the current compiler version. It provides abort!, emit_error!, and related macros for reporting one or many errors tied to specific spans, and can attach a dummy token stream so downstream compilation continues gracefully.

What You Get

• The #[proc_macro_error] attribute that wires up error handling for a macro entry point
• abort!, abort_call_site!, and emit_error! macros for span-attached diagnostics
• Support for notes and help messages alongside the primary error
• Automatic selection of the best diagnostic backend for the current rustc
• Optional dummy token-stream output so the rest of compilation can proceed

Common Use Cases

• Reporting user mistakes in derive and attribute macro input
• Emitting multiple accumulated errors from a single macro expansion
• Migrating panic-based macro error handling to clean compiler diagnostics
• Attaching notes and help text to guide users toward a fix

Under The Hood

Architecture - The crate wraps proc_macro::Diagnostic and compile_error! behind a stable API. src/diagnostic.rs models a diagnostic with a message, spans, and optional notes/help; macros.rs defines the abort!/emit_error! family; dummy.rs handles the fallback token stream; and the imp/ module selects the appropriate backend based on compiler capabilities. A companion proc-macro-error-attr crate supplies the #[proc_macro_error] attribute. Errors are accumulated and flushed as compile_error! invocations when the macro returns.

Tech Stack - Pure Rust, #![forbid(unsafe_code)], dual-licensed Apache-2.0 OR MIT, supporting rustc 1.61+. It builds on syn 2, quote, and proc-macro2, and is structured as a small workspace with the main crate plus the attribute crate and a test crate.

Code Quality - Although it has modest GitHub stars, this fork is widely relied upon (over a hundred million downloads) as the syn-2-compatible successor to proc-macro-error. It forbids unsafe code, ships a CHANGELOG and test suite (including a dedicated test-crate), and preserves the well-documented guide from the original project.

API Design - The macro-driven API reads naturally: annotate your entry point with #[proc_macro_error], then abort!(span, "message"; note = ...; help = ...) wherever validation fails. It mirrors the eventual stable Diagnostic API so code written against it is intended to keep working unchanged once that API lands.