plugin
The tracking issue for this feature is: #29597
This feature is part of "compiler plugins." It will often be used with the
plugin_registrar
and rustc_private
features.
rustc
can load compiler plugins, which are user-provided libraries that
extend the compiler's behavior with new syntax extensions, lint checks, etc.
A plugin is a dynamic library crate with a designated registrar function that
registers extensions with rustc
. Other crates can load these extensions using
the crate attribute #![plugin(...)]
. See the
rustc_plugin
documentation for more about the
mechanics of defining and loading a plugin.
If present, arguments passed as #![plugin(foo(... args ...))]
are not
interpreted by rustc itself. They are provided to the plugin through the
Registry
's args
method.
In the vast majority of cases, a plugin should only be used through
#![plugin]
and not through an extern crate
item. Linking a plugin would
pull in all of libsyntax and librustc as dependencies of your crate. This is
generally unwanted unless you are building another plugin. The
plugin_as_library
lint checks these guidelines.
The usual practice is to put compiler plugins in their own crate, separate from
any macro_rules!
macros or ordinary Rust code meant to be used by consumers
of a library.
Syntax extensions
Plugins can extend Rust's syntax in various ways. One kind of syntax extension is the procedural macro. These are invoked the same way as ordinary macros, but the expansion is performed by arbitrary Rust code that manipulates syntax trees at compile time.
Let's write a plugin
roman_numerals.rs
that implements Roman numeral integer literals.
#![crate_type="dylib"]
#![feature(plugin_registrar, rustc_private)]
extern crate syntax;
extern crate syntax_pos;
extern crate rustc;
extern crate rustc_plugin;
use syntax::parse::token;
use syntax::tokenstream::TokenTree;
use syntax::ext::base::{ExtCtxt, MacResult, DummyResult, MacEager};
use syntax::ext::build::AstBuilder; // A trait for expr_usize.
use syntax_pos::Span;
use rustc_plugin::Registry;
fn expand_rn(cx: &mut ExtCtxt, sp: Span, args: &[TokenTree])
-> Box<MacResult + 'static> {
static NUMERALS: &'static [(&'static str, usize)] = &[
("M", 1000), ("CM", 900), ("D", 500), ("CD", 400),
("C", 100), ("XC", 90), ("L", 50), ("XL", 40),
("X", 10), ("IX", 9), ("V", 5), ("IV", 4),
("I", 1)];
if args.len() != 1 {
cx.span_err(
sp,
&format!("argument should be a single identifier, but got {} arguments", args.len()));
return DummyResult::any(sp);
}
let text = match args[0] {
TokenTree::Token(_, token::Ident(s)) => s.to_string(),
_ => {
cx.span_err(sp, "argument should be a single identifier");
return DummyResult::any(sp);
}
};
let mut text = &*text;
let mut total = 0;
while !text.is_empty() {
match NUMERALS.iter().find(|&&(rn, _)| text.starts_with(rn)) {
Some(&(rn, val)) => {
total += val;
text = &text[rn.len()..];
}
None => {
cx.span_err(sp, "invalid Roman numeral");
return DummyResult::any(sp);
}
}
}
MacEager::expr(cx.expr_usize(sp, total))
}
#[plugin_registrar]
pub fn plugin_registrar(reg: &mut Registry) {
reg.register_macro("rn", expand_rn);
}
Then we can use rn!()
like any other macro:
#![feature(plugin)]
#![plugin(roman_numerals)]
fn main() {
assert_eq!(rn!(MMXV), 2015);
}
The advantages over a simple fn(&str) -> u32
are:
- The (arbitrarily complex) conversion is done at compile time.
- Input validation is also performed at compile time.
- It can be extended to allow use in patterns, which effectively gives a way to define new literal syntax for any data type.
In addition to procedural macros, you can define new
derive
-like attributes and other kinds
of extensions. See Registry::register_syntax_extension
and the
SyntaxExtension
enum. For a more involved macro example, see
regex_macros
.
Tips and tricks
You can use syntax::parse
to turn token trees into
higher-level syntax elements like expressions:
fn expand_foo(cx: &mut ExtCtxt, sp: Span, args: &[TokenTree])
-> Box<MacResult+'static> {
let mut parser = cx.new_parser_from_tts(args);
let expr: P<Expr> = parser.parse_expr();
Looking through libsyntax
parser
code
will give you a feel for how the parsing infrastructure works.
Keep the Span
s of everything you parse, for better error reporting. You can
wrap Spanned
around your custom data structures.
Calling ExtCtxt::span_fatal
will immediately abort compilation. It's better to
instead call ExtCtxt::span_err
and return DummyResult
so that the compiler
can continue and find further errors.
To print syntax fragments for debugging, you can use span_note
together with
syntax::print::pprust::*_to_string
.
The example above produced an integer literal using AstBuilder::expr_usize
.
As an alternative to the AstBuilder
trait, libsyntax
provides a set of
quasiquote macros. They are undocumented and very rough around the edges.
However, the implementation may be a good starting point for an improved
quasiquote as an ordinary plugin library.
Lint plugins
Plugins can extend Rust's lint
infrastructure with
additional checks for code style, safety, etc. Now let's write a plugin
lint_plugin_test.rs
that warns about any item named lintme
.
#![feature(plugin_registrar)]
#![feature(box_syntax, rustc_private)]
extern crate syntax;
// Load rustc as a plugin to get macros
#[macro_use]
extern crate rustc;
extern crate rustc_plugin;
use rustc::lint::{EarlyContext, LintContext, LintPass, EarlyLintPass,
EarlyLintPassObject, LintArray};
use rustc_plugin::Registry;
use syntax::ast;
declare_lint!(TEST_LINT, Warn, "Warn about items named 'lintme'");
struct Pass;
impl LintPass for Pass {
fn get_lints(&self) -> LintArray {
lint_array!(TEST_LINT)
}
}
impl EarlyLintPass for Pass {
fn check_item(&mut self, cx: &EarlyContext, it: &ast::Item) {
if it.ident.as_str() == "lintme" {
cx.span_lint(TEST_LINT, it.span, "item is named 'lintme'");
}
}
}
#[plugin_registrar]
pub fn plugin_registrar(reg: &mut Registry) {
reg.register_early_lint_pass(box Pass as EarlyLintPassObject);
}
Then code like
#![plugin(lint_plugin_test)]
fn lintme() { }
will produce a compiler warning:
foo.rs:4:1: 4:16 warning: item is named 'lintme', #[warn(test_lint)] on by default
foo.rs:4 fn lintme() { }
^~~~~~~~~~~~~~~
The components of a lint plugin are:
-
one or more
declare_lint!
invocations, which define staticLint
structs; -
a struct holding any state needed by the lint pass (here, none);
-
a
LintPass
implementation defining how to check each syntax element. A singleLintPass
may callspan_lint
for several differentLint
s, but should register them all through theget_lints
method.
Lint passes are syntax traversals, but they run at a late stage of compilation
where type information is available. rustc
's built-in
lints
mostly use the same infrastructure as lint plugins, and provide examples of how
to access type information.
Lints defined by plugins are controlled by the usual attributes and compiler
flags, e.g.
#[allow(test_lint)]
or -A test-lint
. These identifiers are derived from the
first argument to declare_lint!
, with appropriate case and punctuation
conversion.
You can run rustc -W help foo.rs
to see a list of lints known to rustc
,
including those provided by plugins loaded by foo.rs
.