]> git.proxmox.com Git - rustc.git/blame - src/doc/rustc-dev-guide/src/rustc-driver.md
New upstream version 1.63.0+dfsg1
[rustc.git] / src / doc / rustc-dev-guide / src / rustc-driver.md
CommitLineData
532ac7d7 1# The Rustc Driver and Interface
a1dfa0c6
XL
2
3The [`rustc_driver`] is essentially `rustc`'s `main()` function. It acts as
4the glue for running the various phases of the compiler in the correct order,
532ac7d7
XL
5using the interface defined in the [`rustc_interface`] crate.
6
7The `rustc_interface` crate provides external users with an (unstable) API
a1dfa0c6
XL
8for running code at particular times during the compilation process, allowing
9third parties to effectively use `rustc`'s internals as a library for
923072b8 10analyzing a crate or emulating the compiler in-process (e.g. the RLS or rustdoc).
532ac7d7 11
ba9703b0 12For those using `rustc` as a library, the [`rustc_interface::run_compiler()`][i_rc]
60c5eb7d 13function is the main entrypoint to the compiler. It takes a configuration for the compiler
ba9703b0 14and a closure that takes a [`Compiler`]. `run_compiler` creates a `Compiler` from the
60c5eb7d
XL
15configuration and passes it to the closure. Inside the closure, you can use the `Compiler`
16to drive queries to compile a crate and get the results. This is what the `rustc_driver` does too.
ba9703b0 17You can see a minimal example of how to use `rustc_interface` [here][example].
532ac7d7
XL
18
19You can see what queries are currently available through the rustdocs for [`Compiler`].
20You can see an example of how to use them by looking at the `rustc_driver` implementation,
21specifically 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
23takes a bunch of command-line args and some other configurations and
24drives the compilation to completion.
532ac7d7 25
ba9703b0
XL
26`rustc_driver::run_compiler` also takes a [`Callbacks`][cb],
27a trait that allows for custom compiler configuration,
28as 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