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_plugin;
  20 //! extern crate rustc_driver;
  21 //! extern crate syntax;
  22 //! extern crate syntax_pos;
  23 //!
  24 //! use rustc_plugin::Registry;
  25 //! use syntax::ext::base::{ExtCtxt, MacResult};
  26 //! use syntax_pos::Span;
  27 //! use syntax::tokenstream::TokenTree;
  28 //!
  29 //! #[plugin_registrar]
  30 //! pub fn plugin_registrar(reg: &mut Registry) {
  31 //!     reg.register_macro("mymacro", expand_mymacro);
  32 //! }
  33 //!
  34 //! fn expand_mymacro(cx: &mut ExtCtxt, span: Span, tt: &[TokenTree]) -> Box<MacResult> {
  35 //!     unimplemented!()
  36 //! }
  37 //!
  38 //! # fn main() {}
  39 //! ```
  40 //!
  41 //! WARNING: We currently don't check that the registrar function
  42 //! has the appropriate type!
  43 //!
  44 //! To use a plugin while compiling another crate:
  45 //!
  46 //! ```rust
  47 //! #![feature(plugin)]
  48 //! #![plugin(myplugin)]
  49 //! ```
  50 //!
  51 //! See the [`plugin`
  52 //! feature](https://doc.rust-lang.org/nightly/unstable-book/language-features/plugin.html)
  53 //! of the Unstable Book for more examples.
  54
  55 #![doc(html_root_url = "https://doc.rust-lang.org/nightly/")]
  56
  57 #![feature(nll)]
  58 #![feature(rustc_diagnostic_macros)]
  59
  60 #![recursion_limit="256"]
  61
  62 pub use registry::Registry;
  63
  64 mod error_codes;
  65 pub mod registry;
  66 pub mod load;
  67 pub mod build;
  68
  69 __build_diagnostic_array! { librustc_plugin, DIAGNOSTICS }