| commit | 30a4e9e3367ee354f671d90035cf7deb1e0d3766 | [log] [tgz] |
|---|---|---|
| author | Alex Crichton <alex@alexcrichton.com> | Fri Apr 27 17:02:19 2018 -0700 |
| committer | Alex Crichton <alex@alexcrichton.com> | Fri Apr 27 22:25:23 2018 -0700 |
| tree | 5b9bae999648f1a7ab186868a1214dc6317a8426 | |
| parent | 6b46debb8e8ed670c5707855e29a5bb0a891ef1b [diff] |
Fix the `nightly` feature outside of rustc This commit is a stab at getting the `proc_macro2` crate to function outside the context of the compiler, **even when the `nightly` feature is enabled**. Previously when the `nightly` feature was enabled then `proc_macro2` would panic at runtime because `proc_macro` itself would panic at runtime due to the lack of the compiler being initialized. In this commit the `unstable` module in `proc_macro2` no longer unconditionally uses the `proc_macro` upstream crate but is rather an `enum` over the upstream crate and the `stable` module. At runtime the appropriate implementation is dynamically selected depending on which works. This brings up some uncomfortable issues such as what happens when you try to psas a "stable span" to a "nightly `Literal`", but I think we can paper over these issues in time by further canonicalizing everything to nightly/stable if it comes up. One caveat this brings up is that `Span::unstable` unconditionally panics when outside the compiler, but I think that's expected regardless.
proc-macro2
A small shim over the proc_macro crate in the compiler intended to multiplex the current stable interface (as of 2017-07-05) and the upcoming richer interface.
The upcoming support has features like:
- Span information on tokens
- No need to go in/out through strings
- Structured input/output
The hope is that libraries ported to proc_macro2 will be trivial to port to the real proc_macro crate once the support on nightly is stabilized.
Usage
This crate by default compiles on the stable version of the compiler. It only uses the stable surface area of the proc_macro crate upstream in the compiler itself. Usage is done via:
[dependencies] proc-macro2 = "0.3"
followed by
extern crate proc_macro; extern crate proc_macro2; #[proc_macro_derive(MyDerive)] pub fn my_derive(input: proc_macro::TokenStream) -> proc_macro::TokenStream { let input: proc_macro2::TokenStream = input.into(); let output: proc_macro2::TokenStream = { /* transform input */ }; output.into() }
If you'd like you can enable the nightly feature in this crate. This will cause it to compile against the unstable and nightly-only features of the proc_macro crate. This in turn requires a nightly compiler. This should help preserve span information, however, coming in from the compiler itself.
You can enable this feature via:
[dependencies] proc-macro2 = { version = "0.3", features = ["nightly"] }
Unstable Features
proc-macro2 supports exporting some methods from proc_macro which are currently highly unstable, and may not be stabilized in the first pass of proc_macro stabilizations. These features are not exported by default. Minor versions of proc-macro2 may make breaking changes to them at any time.
To enable these features, the procmacro2_semver_exempt config flag must be passed to rustc.
RUSTFLAGS='--cfg procmacro2_semver_exempt' cargo build
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.
License
This project is licensed under either of
- Apache License, Version 2.0, (LICENSE-APACHE or http://www.apache.org/licenses/LICENSE-2.0)
- MIT license (LICENSE-MIT or http://opensource.org/licenses/MIT)
at your option.
Contribution
Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in Serde by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.