From d7c28fcec9d13daa84e65b4c51ed6990cf399a3a Mon Sep 17 00:00:00 2001
From: Tbkhi <dining-03town@icloud.com>
Date: Sun, 10 Mar 2024 14:38:24 -0300
Subject: [PATCH] improve rustc-driver.md
minor addition and adding links
Update rustc-driver.md
removing parens for functions
reorganized directory
reorganized directory
minor edits
---
src/SUMMARY.md | 6 +--
src/rustc-driver.md | 45 -----------------
.../getting-diagnostics.md} | 4 +-
.../interacting-with-the-ast.md} | 0
src/rustc-driver/intro.md | 50 +++++++++++++++++++
5 files changed, 55 insertions(+), 50 deletions(-)
delete mode 100644 src/rustc-driver.md
rename src/{rustc-driver-getting-diagnostics.md => rustc-driver/getting-diagnostics.md} (85%)
rename src/{rustc-driver-interacting-with-the-ast.md => rustc-driver/interacting-with-the-ast.md} (100%)
create mode 100644 src/rustc-driver/intro.md
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 <!-- date-check: september 2024 --> `nightly-2024-09-16`:
+and run [`TyCtxt.analysis`].
+The following was tested with <!-- date-check: september 2024 --> `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/