src/doc/rustc-guide/src/rustc-driver.md

   1 # The Rustc Driver and Interface
   2
   3 The [`rustc_driver`] is essentially `rustc`'s `main()` function. It acts as
   4 the glue for running the various phases of the compiler in the correct order,
   5 using the interface defined in the [`rustc_interface`] crate.
   6
   7 The `rustc_interface` crate provides external users with an (unstable) API
   8 for running code at particular times during the compilation process, allowing
   9 third parties to effectively use `rustc`'s internals as a library for
  10 analysing a crate or emulating the compiler in-process (e.g. the RLS or rustdoc).
  11
  12 For those using `rustc` as a library, the [`rustc_interface::interface::run_compiler()`][i_rc]
  13 function is the main entrypoint to the compiler. It takes a configuration for the compiler
  14 and a closure that takes a [`Compiler`]. `run_compiler` creates a `Compiler` from the
  15 configuration and passes it to the closure. Inside the closure, you can use the `Compiler`
  16 to drive queries to compile a crate and get the results. This is what the `rustc_driver` does too.
  17
  18 You can see what queries are currently available through the rustdocs for [`Compiler`].
  19 You can see an example of how to use them by looking at the `rustc_driver` implementation,
  20 specifically the [`rustc_driver::run_compiler` function][rd_rc] (not to be confused with
  21 [`rustc_interface::interface::run_compiler`][i_rc]). The `rustc_driver::run_compiler` function
  22 takes a bunch of command-line args and some other configurations and
  23 drives the compilation to completion.
  24
  25 `rustc_driver::run_compiler` also takes a [`Callbacks`][cb]. In the past, when
  26 the `rustc_driver::run_compiler` was the primary way to use the compiler as a
  27 library, these callbacks were used to have some custom code run after different
  28 phases of the compilation. If you read [Appendix A], you may notice the use of the
  29 types `CompilerCalls` and `CompileController`, which no longer exist. `Callbacks`
  30 replaces this functionality.
  31
  32 > **Warning:** By its very nature, the internal compiler APIs are always going
  33 > to be unstable. That said, we do try not to break things unnecessarily.
  34
  35 ## A Note On Lifetimes
  36
  37 The Rust compiler is a fairly large program containing lots of big data
  38 structures (e.g. the AST, HIR, and the type system) and as such, arenas and
  39 references are heavily relied upon to minimize unnecessary memory use. This
  40 manifests itself in the way people can plug into the compiler, preferring a
  41 "push"-style API (callbacks) instead of the more Rust-ic "pull" style (think
  42 the `Iterator` trait).
  43
  44 Thread-local storage and interning are used a lot through the compiler to reduce
  45 duplication while also preventing a lot of the ergonomic issues due to many
  46 pervasive lifetimes. The `rustc::ty::tls` module is used to access these
  47 thread-locals, although you should rarely need to touch it.
  48
  49 [cb]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_driver/trait.Callbacks.html
  50 [rd_rc]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_driver/fn.run_compiler.html
  51 [i_rc]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_interface/interface/fn.run_compiler.html
  52 [`rustc_interface`]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_interface/index.html
  53 [`rustc_driver`]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_driver/
  54 [`Compiler`]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_interface/interface/struct.Compiler.html
  55 [`Session`]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_session/struct.Session.html
  56 [`TyCtxt`]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc/ty/struct.TyCtxt.html
  57 [`SourceMap`]: https://doc.rust-lang.org/nightly/nightly-rustc/syntax/source_map/struct.SourceMap.html
  58 [stupid-stats]: https://github.com/nrc/stupid-stats
  59 [Appendix A]: appendix/stupid-stats.html