src/librustc_plugin/lib.rs

   1 //! Infrastructure for compiler plugins.
   2 //!
   3 //! Plugins are Rust libraries which extend the behavior of `rustc`
   4 //! in various ways.
   5 //!
   6 //! Plugin authors will use the `Registry` type re-exported by
   7 //! this module, along with its methods. The rest of the module
   8 //! is for use by `rustc` itself.
   9 //!
  10 //! To define a plugin, build a dylib crate with a
  11 //! `#[plugin_registrar]` function:
  12 //!
  13 //! ```no_run
  14 //! #![crate_name = "myplugin"]
  15 //! #![crate_type = "dylib"]
  16 //! #![feature(plugin_registrar)]
  17 //! #![feature(rustc_private)]
  18 //!
  19 //! extern crate rustc_driver;
  20 //! extern crate syntax;
  21 //! extern crate syntax_pos;
  22 //!
  23 //! use rustc_driver::plugin::Registry;
  24 //! use syntax::ext::base::{ExtCtxt, MacResult};
  25 //! use syntax_pos::Span;
  26 //! use syntax::tokenstream::TokenTree;
  27 //!
  28 //! #[plugin_registrar]
  29 //! pub fn plugin_registrar(reg: &mut Registry) {
  30 //!     reg.register_macro("mymacro", expand_mymacro);
  31 //! }
  32 //!
  33 //! fn expand_mymacro(cx: &mut ExtCtxt, span: Span, tt: &[TokenTree]) -> Box<MacResult> {
  34 //!     unimplemented!()
  35 //! }
  36 //!
  37 //! # fn main() {}
  38 //! ```
  39 //!
  40 //! WARNING: We currently don't check that the registrar function
  41 //! has the appropriate type!
  42 //!
  43 //! To use a plugin while compiling another crate:
  44 //!
  45 //! ```rust
  46 //! #![feature(plugin)]
  47 //! #![plugin(myplugin)]
  48 //! ```
  49 //!
  50 //! See the [`plugin`
  51 //! feature](https://doc.rust-lang.org/nightly/unstable-book/language-features/plugin.html)
  52 //! of the Unstable Book for more examples.
  53
  54 #![doc(html_root_url = "https://doc.rust-lang.org/nightly/")]
  55
  56 #![feature(nll)]
  57 #![feature(rustc_diagnostic_macros)]
  58
  59 #![recursion_limit="256"]
  60
  61 pub use registry::Registry;
  62
  63 mod error_codes;
  64 pub mod registry;
  65 pub mod load;
  66 pub mod build;
  67
  68 __build_diagnostic_array! { librustc_plugin, DIAGNOSTICS }