A wrapper around the procedural macro API of the compiler's proc_macro
crate. This library serves two purposes:
-
Bring proc-macro-like functionality to other contexts like build.rs and main.rs. Types from
proc_macro
are entirely specific to procedural macros and cannot ever exist in code outside of a procedural macro. Meanwhileproc_macro2
types may exist anywhere including non-macro code. By developing foundational libraries like syn and quote againstproc_macro2
rather thanproc_macro
, the procedural macro ecosystem becomes easily applicable to many other use cases and we avoid reimplementing non-macro equivalents of those libraries. -
Make procedural macros unit testable. As a consequence of being specific to procedural macros, nothing that uses
proc_macro
can be executed from a unit test. In order for helper libraries or components of a macro to be testable in isolation, they must be implemented usingproc_macro2
.
Usage
The skeleton of a typical procedural macro typically looks like this:
extern crate proc_macro;
# const IGNORE: &str = stringify! ;
#
If parsing with Syn, you'll use parse_macro_input!
instead to
propagate parse errors correctly back to the compiler when parsing fails.
Unstable features
The default feature set of proc-macro2 tracks the most recent stable
compiler API. Functionality in proc_macro
that is not yet stable is not
exposed by proc-macro2 by default.
To opt into the additional APIs available in the most recent nightly
compiler, the procmacro2_semver_exempt
config flag must be passed to
rustc. We will polyfill those nightly-only APIs back to Rust 1.56.0. As
these are unstable APIs that track the nightly compiler, minor versions of
proc-macro2 may make breaking changes to them at any time.
RUSTFLAGS='--cfg procmacro2_semver_exempt'
Note that this must not only be done for your crate, but for any crate that depends on your crate. This infectious nature is intentional, as it serves as a reminder that you are outside of the normal semver guarantees.
Semver exempt methods are marked as such in the proc-macro2 documentation.
Thread-Safety
Most types in this crate are !Sync
because the underlying compiler
types make use of thread-local memory, meaning they cannot be accessed from
a different thread.