Platform Tools Release 30.0.3 (6597393)
-----BEGIN PGP SIGNATURE-----

iF0EABECAB0WIQRDQNE1cO+UXoOBCWTorT+BmrEOeAUCXu1KxAAKCRDorT+BmrEO
eER/AJ441MkiK15w47EMI77aDqf6lvKq4ACfaWvZhJ5rtP+zVjiD0hTxfu0ZZKc=
=wYT2
-----END PGP SIGNATURE-----
Snap for 6533464 from 2a9ae1e038ae7055abc6377094f5734c9a98de75 to sdk-release

Change-Id: I97ff3072e238f5f51b418af4d7c0c615858a6ec8
tree: 0abc4f2d8acf7ee4bc637fba089b11fbf96d2b0f
  1. .cargo_vcs_info.json
  2. .github/
  3. .gitignore
  4. Android.bp
  5. Cargo.toml
  6. Cargo.toml.orig
  7. LICENSE-APACHE
  8. LICENSE-MIT
  9. METADATA
  10. MODULE_LICENSE_APACHE2
  11. OWNERS
  12. README.md
  13. TEST_MAPPING
  14. build.rs
  15. src/
  16. tests/
README.md

proc-macro2

Build Status Latest Version Rust Documentation

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. Meanwhile proc_macro2 types may exist anywhere including non-macro code. By developing foundational libraries like syn and quote against proc_macro2 rather than proc_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 using proc_macro2.

Usage

[dependencies]
proc-macro2 = "1.0"

The skeleton of a typical procedural macro typically looks like this:

extern crate proc_macro;

#[proc_macro_derive(MyDerive)]
pub fn my_derive(input: proc_macro::TokenStream) -> proc_macro::TokenStream {
    let input = proc_macro2::TokenStream::from(input);

    let output: proc_macro2::TokenStream = {
        /* transform input */
    };

    proc_macro::TokenStream::from(output)
}

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.31.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' 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.

Semver exempt methods are marked as such in the proc-macro2 documentation.

License