The tracking issue for this feature is: #38356

This feature flag guards the new procedural macro features as laid out by RFC 1566, which alongside the now-stable custom derives, provide stabilizable alternatives to the compiler plugin API (which requires the use of perma-unstable internal APIs) for programmatically modifying Rust code at compile-time.

The two new procedural macro kinds are:

• Function-like procedural macros which are invoked like regular declarative macros, and:

• Attribute-like procedural macros which can be applied to any item which built-in attributes can be applied to, and which can take arguments in their invocation as well.

Additionally, this feature flag implicitly enables the use_extern_macros feature, which allows macros to be imported like any other item with use statements, as compared to applying #[macro_use] to an extern crate declaration. It is important to note that procedural macros may only be imported in this manner, and will throw an error otherwise.

You must declare the proc_macro feature in both the crate declaring these new procedural macro kinds as well as in any crates that use them.

As with custom derives, procedural macros may only be declared in crates of the proc-macro type, and must be public functions. No other public items may be declared in proc-macro crates, but private items are fine.

To declare your crate as a proc-macro crate, simply add:

[lib]
proc-macro = true

to your Cargo.toml.

Unlike custom derives, however, the name of the function implementing the procedural macro is used directly as the procedural macro's name, so choose carefully.

Additionally, both new kinds of procedural macros return a TokenStream which wholly replaces the original invocation and its input.

As referenced above, the new procedural macros are not meant to be imported via #[macro_use] and will throw an error if they are. Instead, they are meant to be imported like any other item in Rust, with use statements:

#![feature(proc_macro)]

// Where `my_proc_macros` is some crate of type `proc_macro`
extern crate my_proc_macros;

// And declares a `#[proc_macro] pub fn my_bang_macro()` at its root.
use my_proc_macros::my_bang_macro;

fn main() {
    println!("{}", my_bang_macro!());
}

Any panics in a procedural macro implementation will be caught by the compiler and turned into an error message pointing to the problematic invocation. Thus, it is important to make your panic messages as informative as possible: use Option::expect instead of Option::unwrap and Result::expect instead of Result::unwrap, and inform the user of the error condition as unambiguously as you can.

The proc_macro::TokenStream type is hardcoded into the signatures of procedural macro functions for both input and output. It is a wrapper around the compiler's internal representation for a given chunk of Rust code.

These are procedural macros that are invoked like regular declarative macros. They are declared as public functions in crates of the proc_macro type and using the #[proc_macro] attribute. The name of the declared function becomes the name of the macro as it is to be imported and used. The function must be of the kind fn(TokenStream) -> TokenStream where the sole argument is the input to the macro and the return type is the macro's output.

This kind of macro can expand to anything that is valid for the context it is invoked in, including expressions and statements, as well as items.

Note: invocations of this kind of macro require a wrapping [], {} or () like regular macros, but these do not appear in the input, only the tokens between them. The tokens between the braces do not need to be valid Rust syntax.

my_macro_crate/src/lib.rs

#![feature(proc_macro)]

// This is always necessary to get the `TokenStream` typedef.
extern crate proc_macro;

use proc_macro::TokenStream;

#[proc_macro]
pub fn say_hello(_input: TokenStream) -> TokenStream {
    // This macro will accept any input because it ignores it. 
    // To enforce correctness in macros which don't take input,
    // you may want to add `assert!(_input.to_string().is_empty());`.
    "println!(\"Hello, world!\")".parse().unwrap()
}

my_macro_user/Cargo.toml

[dependencies]
my_macro_crate = { path = "<relative path to my_macro_crate>" }

my_macro_user/src/lib.rs

#![feature(proc_macro)]

extern crate my_macro_crate;

use my_macro_crate::say_hello;

fn main() {
    say_hello!();
}

As expected, this prints Hello, world!.

These are arguably the most powerful flavor of procedural macro as they can be applied anywhere attributes are allowed.

They are declared as public functions in crates of the proc-macro type, using the #[proc_macro_attribute] attribute. The name of the function becomes the name of the attribute as it is to be imported and used. The function must be of the kind fn(TokenStream, TokenStream) -> TokenStream where:

The first argument represents any metadata for the attribute (see the reference chapter on attributes). Only the metadata itself will appear in this argument, for example:

• #[my_macro] will get an empty string.
• #[my_macro = "string"] will get = "string".
• #[my_macro(ident)] will get (ident).
• etc.

The second argument is the item that the attribute is applied to. It can be a function, a type definition, an impl block, an extern block, or a module—attribute invocations can take the inner form (#![my_attr]) or outer form (#[my_attr]).

The return type is the output of the macro which wholly replaces the item it was applied to. Thus, if your intention is to merely modify an item, it must be copied to the output. The output must be an item; expressions, statements and bare blocks are not allowed.

There is no restriction on how many items an attribute-like procedural macro can emit as long as they are valid in the given context.

my_macro_crate/src/lib.rs

#![feature(proc_macro)]

extern crate proc_macro;

use proc_macro::TokenStream;

/// Adds a `/// ### Panics` docstring to the end of the input's documentation
///
/// Does not assert that its receiver is a function or method.
#[proc_macro_attribute]
pub fn panics_note(args: TokenStream, input: TokenStream) -> TokenStream {
    let args = args.to_string();
    let mut input = input.to_string();

    assert!(args.starts_with("= \""), "`#[panics_note]` requires an argument of the form \
                                       `#[panics_note = \"panic note here\"]`");

    // Get just the bare note string
    let panics_note = args.trim_matches(&['=', ' ', '"'][..]);

    // The input will include all docstrings regardless of where the attribute is placed,
    // so we need to find the last index before the start of the item
    let insert_idx = idx_after_last_docstring(&input);

    // And insert our `### Panics` note there so it always appears at the end of an item's docs
    input.insert_str(insert_idx, &format!("/// # Panics \n/// {}\n", panics_note));

    input.parse().unwrap()
}

// `proc-macro` crates can contain any kind of private item still
fn idx_after_last_docstring(input: &str) -> usize {
    // Skip docstring lines to find the start of the item proper
    input.lines().skip_while(|line| line.trim_left().starts_with("///")).next()
        // Find the index of the first non-docstring line in the input
        // Note: assumes this exact line is unique in the input
        .and_then(|line_after| input.find(line_after))
        // No docstrings in the input
        .unwrap_or(0)
}

my_macro_user/Cargo.toml

[dependencies]
my_macro_crate = { path = "<relative path to my_macro_crate>" }

my_macro_user/src/lib.rs

#![feature(proc_macro)]

extern crate my_macro_crate;

use my_macro_crate::panics_note;

/// Do the `foo` thing.
#[panics_note = "Always."]
pub fn foo() {
    panic!()
}

Then the rendered documentation for pub fn foo will look like this:

pub fn foo()

---

Do the foo thing.

Panics

Always.