1# proc-macro2 2 3[<img alt="github" src="https://img.shields.io/badge/github-dtolnay/proc--macro2-8da0cb?style=for-the-badge&labelColor=555555&logo=github" height="20">](https://github.com/dtolnay/proc-macro2) 4[<img alt="crates.io" src="https://img.shields.io/crates/v/proc-macro2.svg?style=for-the-badge&color=fc8d62&logo=rust" height="20">](https://crates.io/crates/proc-macro2) 5[<img alt="docs.rs" src="https://img.shields.io/badge/docs.rs-proc--macro2-66c2a5?style=for-the-badge&labelColor=555555&logo=docs.rs" height="20">](https://docs.rs/proc-macro2) 6[<img alt="build status" src="https://img.shields.io/github/actions/workflow/status/dtolnay/proc-macro2/ci.yml?branch=master&style=for-the-badge" height="20">](https://github.com/dtolnay/proc-macro2/actions?query=branch%3Amaster) 7 8A wrapper around the procedural macro API of the compiler's `proc_macro` crate. 9This library serves two purposes: 10 11- **Bring proc-macro-like functionality to other contexts like build.rs and 12 main.rs.** Types from `proc_macro` are entirely specific to procedural macros 13 and cannot ever exist in code outside of a procedural macro. Meanwhile 14 `proc_macro2` types may exist anywhere including non-macro code. By developing 15 foundational libraries like [syn] and [quote] against `proc_macro2` rather 16 than `proc_macro`, the procedural macro ecosystem becomes easily applicable to 17 many other use cases and we avoid reimplementing non-macro equivalents of 18 those libraries. 19 20- **Make procedural macros unit testable.** As a consequence of being specific 21 to procedural macros, nothing that uses `proc_macro` can be executed from a 22 unit test. In order for helper libraries or components of a macro to be 23 testable in isolation, they must be implemented using `proc_macro2`. 24 25[syn]: https://github.com/dtolnay/syn 26[quote]: https://github.com/dtolnay/quote 27 28## Usage 29 30```toml 31[dependencies] 32proc-macro2 = "1.0" 33``` 34 35The skeleton of a typical procedural macro typically looks like this: 36 37```rust 38extern crate proc_macro; 39 40#[proc_macro_derive(MyDerive)] 41pub fn my_derive(input: proc_macro::TokenStream) -> proc_macro::TokenStream { 42 let input = proc_macro2::TokenStream::from(input); 43 44 let output: proc_macro2::TokenStream = { 45 /* transform input */ 46 }; 47 48 proc_macro::TokenStream::from(output) 49} 50``` 51 52If parsing with [Syn], you'll use [`parse_macro_input!`] instead to propagate 53parse errors correctly back to the compiler when parsing fails. 54 55[`parse_macro_input!`]: https://docs.rs/syn/1.0/syn/macro.parse_macro_input.html 56 57## Unstable features 58 59The default feature set of proc-macro2 tracks the most recent stable compiler 60API. Functionality in `proc_macro` that is not yet stable is not exposed by 61proc-macro2 by default. 62 63To opt into the additional APIs available in the most recent nightly compiler, 64the `procmacro2_semver_exempt` config flag must be passed to rustc. We will 65polyfill those nightly-only APIs back to Rust 1.31.0. As these are unstable APIs 66that track the nightly compiler, minor versions of proc-macro2 may make breaking 67changes to them at any time. 68 69``` 70RUSTFLAGS='--cfg procmacro2_semver_exempt' cargo build 71``` 72 73Note that this must not only be done for your crate, but for any crate that 74depends on your crate. This infectious nature is intentional, as it serves as a 75reminder that you are outside of the normal semver guarantees. 76 77Semver exempt methods are marked as such in the proc-macro2 documentation. 78 79<br> 80 81#### License 82 83<sup> 84Licensed under either of <a href="LICENSE-APACHE">Apache License, Version 852.0</a> or <a href="LICENSE-MIT">MIT license</a> at your option. 86</sup> 87 88<br> 89 90<sub> 91Unless you explicitly state otherwise, any contribution intentionally submitted 92for inclusion in this crate by you, as defined in the Apache-2.0 license, shall 93be dual licensed as above, without any additional terms or conditions. 94</sub> 95
