Crate rustc_tools

rustc-tools

Some internal rustc tools made accessible (by wrapping the setup part away).

API documentation is available here.

The versioning is following the official Rust version it’s matching. So version 0.78 means it’s on par with Rust 1.78.

Why would I need this crate?

If you need to write a Rust compiler plugin (clippy and rustdoc are good examples of what a rustc plugin can achieve), a lot of setup is required to be able to use its APIs. This crate aims at removing this pain point so you can spend more time working on the plugin instead.

How to use it?

Since it provides and uses rustc API, it only works on a very specific nightly version of the Rust compiler. Copy the rust-toolchain file into your project.

Another thing required: you need to add #![feature(rustc_private) in your crate to be able to use rustc_tools.

Once done, that’s it!

Global explanations

In the Rust compiler, there are multiple levels to handle APIs. The lower you go, the more information you have. What follows are very simplified explanations:

First, you have the lexer. It is an iterator which goes through a string (a source code file) and tries to parse it as Rust code. It doesn’t do anything else like trying to follow module declarations or anything, it just generates syntax information.

Then, you have the ast which gives more information about what you’re reading and classifies it. For example, you don’t have just tokens anymore but items. At this level, you can start using visitors as you already have some nice information like attributes, visibility, etc. Take a look at examples/ast.rs to see an example.

The final level covered by this crate is HIR (for High-level Intermediate Representation). You get it after macro expansion and name resolution. It is made to be a compiler-friendly AST. As such, you can start using the internal Rust compiler query system with it.

If you want more information about all this, I strongly recommend you to go read the rustc dev guide and to take a look at the compiler documentation (and in particular the TyCtxt and Map types, both of which are at the center of the HIR level).

Running examples

There are a few examples available in the examples folder. To run them:

$ cargo run --example ast -- asset/example_file.rs
$ cargo run --example hir -- asset/example_file.rs
$ cargo run --example lint -- asset/example_file.rs

A more complete example with cargo integration is available here.

Enums

• Error
  Error returned by the API. If the parser encounters a problem, it’ll always be Error::Parser. Error::Other is for users.

Functions

• cargo_integration
  Allows your rustc plugin to run directly with cargo integration. Quite useful in case you are writing a cargo tool.
• get_supported_rustc_version
  Returns the rustc version rustc-tools is currently using.
• lexer
  Very basic lexer which return a lexer iterator. It doesn’t handle errors or anything. For more advanced usage, take a look at with_ast_parser instead.
• with_ast_parser
  You can check ParseSess documentation here and Crate documentation here.
• with_lints
  If you want to create a linter, this the function you want to use.
• with_tyctxt
  If you need more information than what is provided by with_ast_parser, this is the function you will use.