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 in the examples/with-cargo-integration.