]>
Commit | Line | Data |
---|---|---|
532ac7d7 | 1 | # The Rustc Driver and Interface |
a1dfa0c6 XL |
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, | |
532ac7d7 XL |
5 | using the interface defined in the [`rustc_interface`] crate. |
6 | ||
7 | The `rustc_interface` crate provides external users with an (unstable) API | |
a1dfa0c6 XL |
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 | |
923072b8 | 10 | analyzing a crate or emulating the compiler in-process (e.g. the RLS or rustdoc). |
532ac7d7 | 11 | |
ba9703b0 | 12 | For those using `rustc` as a library, the [`rustc_interface::run_compiler()`][i_rc] |
60c5eb7d | 13 | function is the main entrypoint to the compiler. It takes a configuration for the compiler |
ba9703b0 | 14 | and a closure that takes a [`Compiler`]. `run_compiler` creates a `Compiler` from the |
60c5eb7d XL |
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. | |
ba9703b0 | 17 | You can see a minimal example of how to use `rustc_interface` [here][example]. |
532ac7d7 XL |
18 | |
19 | You can see what queries are currently available through the rustdocs for [`Compiler`]. | |
20 | You can see an example of how to use them by looking at the `rustc_driver` implementation, | |
21 | specifically the [`rustc_driver::run_compiler` function][rd_rc] (not to be confused with | |
ba9703b0 | 22 | [`rustc_interface::run_compiler`][i_rc]). The `rustc_driver::run_compiler` function |
60c5eb7d XL |
23 | takes a bunch of command-line args and some other configurations and |
24 | drives the compilation to completion. | |
532ac7d7 | 25 | |
ba9703b0 XL |
26 | `rustc_driver::run_compiler` also takes a [`Callbacks`][cb], |
27 | a trait that allows for custom compiler configuration, | |
28 | as well as allowing some custom code run after different phases of the compilation. | |
a1dfa0c6 XL |
29 | |
30 | > **Warning:** By its very nature, the internal compiler APIs are always going | |
31 | > to be unstable. That said, we do try not to break things unnecessarily. | |
32 | ||
a1dfa0c6 | 33 | |
532ac7d7 XL |
34 | [cb]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_driver/trait.Callbacks.html |
35 | [rd_rc]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_driver/fn.run_compiler.html | |
60c5eb7d | 36 | [i_rc]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_interface/interface/fn.run_compiler.html |
ba9703b0 | 37 | [example]: https://github.com/rust-lang/rustc-dev-guide/blob/master/examples/rustc-driver-example.rs |
532ac7d7 | 38 | [`rustc_interface`]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_interface/index.html |
a1dfa0c6 | 39 | [`rustc_driver`]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_driver/ |
532ac7d7 | 40 | [`Compiler`]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_interface/interface/struct.Compiler.html |
60c5eb7d | 41 | [`Session`]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_session/struct.Session.html |
ba9703b0 | 42 | [`TyCtxt`]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_middle/ty/struct.TyCtxt.html |
dfeec247 | 43 | [`SourceMap`]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_span/source_map/struct.SourceMap.html |
a1dfa0c6 XL |
44 | [stupid-stats]: https://github.com/nrc/stupid-stats |
45 | [Appendix A]: appendix/stupid-stats.html |