README.md
1# proc-macro2
2
3[](https://github.com/alexcrichton/proc-macro2/actions)
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}