diff --git a/src/SUMMARY.md b/src/SUMMARY.md index 12ab10d50..3449ca428 100644 --- a/src/SUMMARY.md +++ b/src/SUMMARY.md @@ -90,9 +90,9 @@ - [Prologue](./part-3-intro.md) - [Command-line arguments](./cli.md) -- [rustc_driver and rustc_interface](./rustc-driver.md) - - [Example: Type checking](./rustc-driver-interacting-with-the-ast.md) - - [Example: Getting diagnostics](./rustc-driver-getting-diagnostics.md) +- [rustc_driver and rustc_interface](./rustc-driver/intro.md) + - [Example: Type checking](./rustc-driver/interacting-with-the-ast.md) + - [Example: Getting diagnostics](./rustc-driver/getting-diagnostics.md) - [Syntax and the AST](./syntax-intro.md) - [Lexing and Parsing](./the-parser.md) - [Macro expansion](./macro-expansion.md) diff --git a/src/rustc-driver.md b/src/rustc-driver.md deleted file mode 100644 index bae98c746..000000000 --- a/src/rustc-driver.md +++ /dev/null @@ -1,45 +0,0 @@ -# `rustc_driver` and `rustc_interface` - -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. - -The `rustc_interface` crate provides external users with an (unstable) API -for running code at particular times during the compilation process, allowing -third parties to effectively use `rustc`'s internals as a library for -analyzing a crate or emulating the compiler in-process (e.g. rustdoc). - -For those using `rustc` as a library, the [`rustc_interface::run_compiler()`][i_rc] -function is the main entrypoint to the compiler. It takes a configuration for the compiler -and a closure that takes a [`Compiler`]. `run_compiler` creates a `Compiler` from the -configuration and passes it to the closure. Inside the closure, you can use the `Compiler` -to drive queries to compile a crate and get the results. This is what the `rustc_driver` does too. -You can see a minimal example of how to use `rustc_interface` [here][example]. - -You can see what queries are currently available through the rustdocs for [`Compiler`]. -You can see an example of how to use them by looking at the `rustc_driver` implementation, -specifically the [`rustc_driver::run_compiler` function][rd_rc] (not to be confused with -[`rustc_interface::run_compiler`][i_rc]). The `rustc_driver::run_compiler` function -takes a bunch of command-line args and some other configurations and -drives the compilation to completion. - -`rustc_driver::run_compiler` also takes a [`Callbacks`][cb], -a trait that allows for custom compiler configuration, -as well as allowing some custom code run after different phases of the compilation. - -> **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. - - -[cb]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_driver/trait.Callbacks.html -[rd_rc]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_driver_impl/fn.run_compiler.html -[i_rc]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_interface/interface/fn.run_compiler.html -[example]: https://github.com/rust-lang/rustc-dev-guide/blob/master/examples/rustc-driver-example.rs -[`rustc_interface`]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_interface/index.html -[`rustc_driver`]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_driver/ -[`Compiler`]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_interface/interface/struct.Compiler.html -[`Session`]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_session/struct.Session.html -[`TyCtxt`]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_middle/ty/struct.TyCtxt.html -[`SourceMap`]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_span/source_map/struct.SourceMap.html -[stupid-stats]: https://github.com/nrc/stupid-stats -[Appendix A]: appendix/stupid-stats.html diff --git a/src/rustc-driver-getting-diagnostics.md b/src/rustc-driver/getting-diagnostics.md similarity index 85% rename from src/rustc-driver-getting-diagnostics.md rename to src/rustc-driver/getting-diagnostics.md index a92522684..ab894f1c8 100644 --- a/src/rustc-driver-getting-diagnostics.md +++ b/src/rustc-driver/getting-diagnostics.md @@ -7,8 +7,8 @@ otherwise be printed to stderr. To get diagnostics from the compiler, configure [`rustc_interface::Config`] to output diagnostic to a buffer, -and run [`TyCtxt.analysis`]. The following was tested -with `nightly-2024-09-16`: +and run [`TyCtxt.analysis`]. +The following was tested with `nightly-2024-09-16`: ```rust {{#include ../examples/rustc-driver-getting-diagnostics.rs}} diff --git a/src/rustc-driver-interacting-with-the-ast.md b/src/rustc-driver/interacting-with-the-ast.md similarity index 100% rename from src/rustc-driver-interacting-with-the-ast.md rename to src/rustc-driver/interacting-with-the-ast.md diff --git a/src/rustc-driver/intro.md b/src/rustc-driver/intro.md new file mode 100644 index 000000000..76cbdd06e --- /dev/null +++ b/src/rustc-driver/intro.md @@ -0,0 +1,50 @@ +# `rustc_driver` and `rustc_interface` + +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. + +Generally the [`rustc_interface`] crate provides external users with an (unstable) API +for running code at particular times during 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 (i.e. `rustdoc` +compiling code and serving output). + +More specifically the [`rustc_interface::run_compiler`][i_rc] function is the +main entrypoint for using [`nightly-rustc`] as a library. +Initially [`run_compiler`][i_rc] takes a configuration variable for the compiler +and a `closure` taking a yet unresolved [`Compiler`]. +Operationally [`run_compiler`][i_rc] creates a `Compiler` from the configuration and passes +it to the `closure`. Inside the `closure` you can use the `Compiler` to drive +queries to compile a crate and get the results. +Providing results about the internal state of the compiler what the [`rustc_driver`] does too. +You can see a minimal example of how to use [`rustc_interface`] [here][example]. + +You can see what queries are currently available in the [`Compiler`] rustdocs. +You can see an example of how to use the queries by looking at the `rustc_driver` implementation, +specifically [`rustc_driver::run_compiler`][rd_rc] +(not to be confused with [`rustc_interface::run_compiler`][i_rc]). +Generally [`rustc_driver::run_compiler`][i_rc] takes a bunch of command-line args +and some other configurations and drives the compilation to completion. + +Finally [`rustc_driver::run_compiler`][rd_rc] also takes a [`Callbacks`][cb], +which is a `trait` that allows for custom compiler configuration, +as well as allowing custom code to run after different phases of the compilation. + +> **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. + + +[`Compiler`]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_interface/interface/struct.Compiler.html +[`rustc_driver`]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_driver/ +[`rustc_interface`]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_interface/index.html +[`Session`]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_session/struct.Session.html +[`SourceMap`]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_span/source_map/struct.SourceMap.html +[`TyCtxt`]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_middle/ty/struct.TyCtxt.html +[Appendix A]: appendix/stupid-stats.html +[cb]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_driver/trait.Callbacks.html +[example]: https://github.com/rust-lang/rustc-dev-guide/blob/master/examples/rustc-driver-example.rs +[i_rc]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_interface/interface/fn.run_compiler.html +[rd_rc]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_driver_impl/fn.run_compiler.html +[stupid-stats]: https://github.com/nrc/stupid-stats +[`nightly-rustc`]: https://doc.rust-lang.org/nightly/nightly-rustc/