Macros migration

gistfile1.md

With Rust 1.0-alpha, the macro reform RFC is mostly implemented. This document gives a quick guide to migrating your code.

Macro syntax

#[macro_use] extern crate

A macro import such as

#[phase(plugin, link)]
extern crate baz;

should become

#[macro_use]
extern crate baz;

There is no feature gate required for macro_use.

You can optionally limit the set of imported macros:

#[macro_use(foo, bar)]
extern crate baz;

If a crate only provides macros and should not be linked, use

#[macro_use] #[no_link]
extern crate baz;

This takes the place of #[phase(plugin)].

#[macro_escape] → #[macro_use]

#[macro_use] is also used on mod items, as the replacement for #[macro_escape].

Code which used an inner attribute:

mod foo {
    #![macro_escape]

    ...
}

should change to an outer attribute:

#[macro_use]
mod foo {
    ...
}

for consistency with the extern crate form.

macro_rules! is no longer feature gated

Yay!

macro_rules! syntax convention

Old macro definitions of the form

macro_rules! foo(
    ($x:expr) => ($x)
);

should change to

macro_rules! foo {
    ($x:expr) => ($x)
}

for consistency with other kinds of definitions in the language (fn, struct, etc.)

macro is a keyword

Unused, but reserved for an improved macro system in the future.

$crate

The special macro variable $crate facilitates cross-crate macro usage. See the Macros Guide for more information.

#[macro_reexport]

Imported macros can now be re-exported. This is mostly intended for use by the libstd "facade" crate. See the Reference for more information.

Compiler plugins

Loading a compiler plugin is now accomplished with

#![feature(plugin)]

#[plugin]
extern crate baz;

As with macro crates, you can also specify #[no_link]. If a plugin crate provides ordinary macros as well, you can combine #[plugin] and #[macro_use].

Arguments passed as #[plugin=...] or #[plugin(...)] are not interpreted by rustc itself. They are provided to the plugin through the Registry's args method and can be used for configuration.

Very useful

Looks like http://doc.rust-lang.org/guide-macros.html is not up-to-date yet. In the meantime: https://github.com/rust-lang/rust/blob/master/src/doc/guide-macros.md#the-variable-crate

It's up to date now; I think it happens with the nightly build.