An Unofficial Guide to Using Rustc
Many people familiar with C and C++ will have heard of libclang. This is a
really powerful library which gives you access to the internals of the
compiler so you can analyse a C/C++ program, or even rewrite bits of it on the
fly. This allows you to write tools for detecting undefined behaviour or
insert additional statements to help calculate code coverage.
The Rust compiler gives you hooks for analysing or manipulating a program
during the compilation process. This is arguably more powerful because you
have access to all of the compiler internals... With the trade-off being
you can only access it from nightly given the perpetually unstable nature of
these internals (
rustc and the Rust language are continually evolving after
This tutorial should hopefully give you a better understanding of the
compilation process and how you can plug into
rustc to do magical and
wonderous things. It's written from the point-of-view of someone wanting to
write a generic Rust crate analyser as a
cargo subcommand (
Useful Links and Prior Art
Often the easiest way to get started is to look at existing uses of
internals in the wild and adapt what they've done to your use case.
Here are several repositories which already use
rustc for analysing Rust
- Stupid Stats (highly recommended - I actually based this tutorial on
You don't need anything special to start using
rustc's internals, just
nightly and you should be able to follow along.
$ rustup default nightly
While it's not required, it's quite useful to have a copy of the
rustc (and its various other crates) handy, as well as a local
checkout of the rust-lang/rust repo. I've set up a cron job on my laptop to
periodically regenerate the internal compiler documentation and push them to
GitHub Pages to make your life easier.