rustc_driver and rustc_interface - Rust Compiler Development Guide (original) (raw)

Rust Compiler Development Guide

rustc_driver and rustc_interface

rustc_driver

The rustc_driver is essentially rustc's main function. It acts as the glue for running the various phases of the compiler in the correct order, using the interface defined in the rustc_interface crate. Where possible, using rustc_driver rather than rustc_interface is recommended.

The main entry point of rustc_driver is rustc_driver::run_compiler. This builder accepts the same command-line args as rustc as well as an implementation of Callbacks and a couple of other optional options.Callbacks is a trait that allows for custom compiler configuration, as well as allowing custom code to run after different phases of the compilation.

rustc_interface

The rustc_interface crate provides a low level API to external users for manually driving the compilation process, allowing third parties to effectively use rustc's internals as a library for analyzing a crate or for ad hoc emulating of the compiler for cases where rustc_driver is not flexible enough (i.e. rustdoc compiling code and serving output).

The main entry point of rustc_interface (rustc_interface::run_compiler) takes a configuration variable for the compiler and a closure taking a yet unresolved Compiler.run_compiler creates a Compiler from the configuration and passes it to the closure. Inside the closure you can use the Compiler to call various functions to compile a crate and get the results. You can see a minimal example of how to use rustc_interface here.

You can see an example of how to use the various functions using rustc_interface needs by looking at the rustc_driver implementation, specifically rustc_driver_impl::run_compiler(not to be confused with rustc_interface::run_compiler).

Warning: By its very nature, the internal compiler APIs are always going to be unstable. That said, we do try not to break things unnecessarily.