[rustc.git] / src / doc / reference / src / procedural-macros.md

## Procedural Macros

*Procedural macros* allow creating syntax extensions as execution of a function.
Procedural macros can be used for is to implement custom [derive] on your own
types. See [the book][procedural macros] for a tutorial.

Procedural macros involve a few different parts of the language and its
standard libraries. First is the `proc_macro` crate, included with Rust,
that defines an interface for building a procedural macro. The
`#[proc_macro_derive(Foo)]` attribute is used to mark the deriving
function. This function must have the type signature:

```rust,ignore
use proc_macro::TokenStream;

#[proc_macro_derive(Hello)]
pub fn hello_world(input: TokenStream) -> TokenStream
```

Finally, procedural macros must be in their own crate, with the `proc-macro`
crate type.

[derive]: attributes.html#derive
[procedural macros]: ../book/first-edition/procedural-macros.html
Commit	Line	Data
8bb4bdeb XL	1	## Procedural Macros
8bb4bdeb XL	2
abe05a73 XL	3	Procedural macros allow creating syntax extensions as execution of a function.
	4	Procedural macros can be used for is to implement custom [derive] on your own
	5	types. See [the book][procedural macros] for a tutorial.
8bb4bdeb XL	6
	7	Procedural macros involve a few different parts of the language and its
	8	standard libraries. First is the `proc_macro` crate, included with Rust,
	9	that defines an interface for building a procedural macro. The
	10	`#[proc_macro_derive(Foo)]` attribute is used to mark the deriving
	11	function. This function must have the type signature:
	12
	13	```rust,ignore
	14	use proc_macro::TokenStream;
	15
	16	#[proc_macro_derive(Hello)]
	17	pub fn hello_world(input: TokenStream) -> TokenStream
	18	```
	19
	20	Finally, procedural macros must be in their own crate, with the `proc-macro`
	21	crate type.
abe05a73 XL	22
	23	[derive]: attributes.html#derive
	24	[procedural macros]: ../book/first-edition/procedural-macros.html