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