From 4013f453e51a6cf4bf83531f583f048c9cc7e6dc Mon Sep 17 00:00:00 2001 From: Mark Mansi Date: Fri, 15 Mar 2019 17:24:46 -0500 Subject: [PATCH 1/3] chalk has moved to rust-lang --- src/traits/chalk-overview.md | 64 ++++++++++++++++++------------------ src/traits/slg.md | 8 ++--- 2 files changed, 36 insertions(+), 36 deletions(-) diff --git a/src/traits/chalk-overview.md b/src/traits/chalk-overview.md index 59572479d..54046b22e 100644 --- a/src/traits/chalk-overview.md +++ b/src/traits/chalk-overview.md @@ -172,7 +172,7 @@ Chalk's functionality is broken up into the following crates: - `coherence`, which implements coherence rules - Also includes [chalki][chalki], chalk's REPL. -[Browse source code on GitHub](https://github.com/rust-lang-nursery/chalk) +[Browse source code on GitHub](https://github.com/rust-lang/chalk) ## Testing @@ -202,8 +202,8 @@ Likewise, lowering tests use the [`lowering_success!` and ## More Resources -* [Chalk Source Code](https://github.com/rust-lang-nursery/chalk) -* [Chalk Glossary](https://github.com/rust-lang-nursery/chalk/blob/master/GLOSSARY.md) +* [Chalk Source Code](https://github.com/rust-lang/chalk) +* [Chalk Glossary](https://github.com/rust-lang/chalk/blob/master/GLOSSARY.md) ### Blog Posts @@ -224,34 +224,34 @@ Likewise, lowering tests use the [`lowering_success!` and [wf-checking]: ./wf.html [ast]: https://en.wikipedia.org/wiki/Abstract_syntax_tree -[chalk]: https://github.com/rust-lang-nursery/chalk -[rustc-issues]: https://github.com/rust-lang-nursery/rustc-guide/issues +[chalk]: https://github.com/rust-lang/chalk +[rustc-issues]: https://github.com/rust-lang/rustc-guide/issues [universal quantification]: https://en.wikipedia.org/wiki/Universal_quantification -[`ProgramClause`]: https://rust-lang-nursery.github.io/chalk/doc/chalk_ir/enum.ProgramClause.html -[`ProgramEnvironment`]: https://rust-lang-nursery.github.io/chalk/doc/chalk_ir/struct.ProgramEnvironment.html -[chalk_engine]: https://rust-lang-nursery.github.io/chalk/doc/chalk_engine/index.html -[chalk_ir]: https://rust-lang-nursery.github.io/chalk/doc/chalk_ir/index.html -[chalk_parse]: https://rust-lang-nursery.github.io/chalk/doc/chalk_parse/index.html -[chalk_solve]: https://rust-lang-nursery.github.io/chalk/doc/chalk_solve/index.html -[doc-chalk]: https://rust-lang-nursery.github.io/chalk/doc/chalk/index.html -[engine-context]: https://rust-lang-nursery.github.io/chalk/doc/chalk_engine/context/index.html -[rust_ir-program]: https://rust-lang-nursery.github.io/chalk/doc/chalk/rust_ir/struct.Program.html -[rust_ir]: https://rust-lang-nursery.github.io/chalk/doc/chalk/rust_ir/index.html - -[binders-struct]: https://github.com/rust-lang-nursery/chalk/blob/94a1941a021842a5fcb35cd043145c8faae59f08/src/ir.rs#L661 -[chalk-ast]: https://github.com/rust-lang-nursery/chalk/blob/master/chalk-parse/src/ast.rs -[chalk-test-example]: https://github.com/rust-lang-nursery/chalk/blob/4bce000801de31bf45c02f742a5fce335c9f035f/src/test.rs#L115 -[chalk-test-lowering-example]: https://github.com/rust-lang-nursery/chalk/blob/4bce000801de31bf45c02f742a5fce335c9f035f/src/rust_ir/lowering/test.rs#L8-L31 -[chalk-test-lowering]: https://github.com/rust-lang-nursery/chalk/blob/4bce000801de31bf45c02f742a5fce335c9f035f/src/rust_ir/lowering/test.rs -[chalk-test-wf]: https://github.com/rust-lang-nursery/chalk/blob/4bce000801de31bf45c02f742a5fce335c9f035f/src/rules/wf/test.rs#L1 -[chalki]: https://rust-lang-nursery.github.io/chalk/doc/chalki/index.html -[clause]: https://github.com/rust-lang-nursery/chalk/blob/master/GLOSSARY.md#clause -[coherence-src]: https://github.com/rust-lang-nursery/chalk/blob/master/src/coherence.rs -[ir-code]: https://github.com/rust-lang-nursery/chalk/blob/master/src/rust_ir.rs -[rules-environment]: https://github.com/rust-lang-nursery/chalk/blob/94a1941a021842a5fcb35cd043145c8faae59f08/src/rules.rs#L9 -[rules-src]: https://github.com/rust-lang-nursery/chalk/blob/4bce000801de31bf45c02f742a5fce335c9f035f/src/rules.rs -[rules-wf-src]: https://github.com/rust-lang-nursery/chalk/blob/4bce000801de31bf45c02f742a5fce335c9f035f/src/rules/wf.rs -[solve_goal]: https://github.com/rust-lang-nursery/chalk/blob/4bce000801de31bf45c02f742a5fce335c9f035f/src/test.rs#L85 -[test-lowering-macros]: https://github.com/rust-lang-nursery/chalk/blob/4bce000801de31bf45c02f742a5fce335c9f035f/src/test_util.rs#L21-L54 -[test-macro]: https://github.com/rust-lang-nursery/chalk/blob/4bce000801de31bf45c02f742a5fce335c9f035f/src/test.rs#L33 +[`ProgramClause`]: https://rust-lang.github.io/chalk/doc/chalk_ir/enum.ProgramClause.html +[`ProgramEnvironment`]: https://rust-lang.github.io/chalk/doc/chalk_ir/struct.ProgramEnvironment.html +[chalk_engine]: https://rust-lang.github.io/chalk/doc/chalk_engine/index.html +[chalk_ir]: https://rust-lang.github.io/chalk/doc/chalk_ir/index.html +[chalk_parse]: https://rust-lang.github.io/chalk/doc/chalk_parse/index.html +[chalk_solve]: https://rust-lang.github.io/chalk/doc/chalk_solve/index.html +[doc-chalk]: https://rust-lang.github.io/chalk/doc/chalk/index.html +[engine-context]: https://rust-lang.github.io/chalk/doc/chalk_engine/context/index.html +[rust_ir-program]: https://rust-lang.github.io/chalk/doc/chalk/rust_ir/struct.Program.html +[rust_ir]: https://rust-lang.github.io/chalk/doc/chalk/rust_ir/index.html + +[binders-struct]: https://github.com/rust-lang/chalk/blob/94a1941a021842a5fcb35cd043145c8faae59f08/src/ir.rs#L661 +[chalk-ast]: https://github.com/rust-lang/chalk/blob/master/chalk-parse/src/ast.rs +[chalk-test-example]: https://github.com/rust-lang/chalk/blob/4bce000801de31bf45c02f742a5fce335c9f035f/src/test.rs#L115 +[chalk-test-lowering-example]: https://github.com/rust-lang/chalk/blob/4bce000801de31bf45c02f742a5fce335c9f035f/src/rust_ir/lowering/test.rs#L8-L31 +[chalk-test-lowering]: https://github.com/rust-lang/chalk/blob/4bce000801de31bf45c02f742a5fce335c9f035f/src/rust_ir/lowering/test.rs +[chalk-test-wf]: https://github.com/rust-lang/chalk/blob/4bce000801de31bf45c02f742a5fce335c9f035f/src/rules/wf/test.rs#L1 +[chalki]: https://rust-lang.github.io/chalk/doc/chalki/index.html +[clause]: https://github.com/rust-lang/chalk/blob/master/GLOSSARY.md#clause +[coherence-src]: https://github.com/rust-lang/chalk/blob/master/src/coherence.rs +[ir-code]: https://github.com/rust-lang/chalk/blob/master/src/rust_ir.rs +[rules-environment]: https://github.com/rust-lang/chalk/blob/94a1941a021842a5fcb35cd043145c8faae59f08/src/rules.rs#L9 +[rules-src]: https://github.com/rust-lang/chalk/blob/4bce000801de31bf45c02f742a5fce335c9f035f/src/rules.rs +[rules-wf-src]: https://github.com/rust-lang/chalk/blob/4bce000801de31bf45c02f742a5fce335c9f035f/src/rules/wf.rs +[solve_goal]: https://github.com/rust-lang/chalk/blob/4bce000801de31bf45c02f742a5fce335c9f035f/src/test.rs#L85 +[test-lowering-macros]: https://github.com/rust-lang/chalk/blob/4bce000801de31bf45c02f742a5fce335c9f035f/src/test_util.rs#L21-L54 +[test-macro]: https://github.com/rust-lang/chalk/blob/4bce000801de31bf45c02f742a5fce335c9f035f/src/test.rs#L33 diff --git a/src/traits/slg.md b/src/traits/slg.md index dcddd01f5..98547575d 100644 --- a/src/traits/slg.md +++ b/src/traits/slg.md @@ -47,7 +47,7 @@ well as the various *strands*, which are basically suspended computations that may be used to find more answers. Tables are interdependent: solving one query may require solving others. -[`Forest`]: https://rust-lang-nursery.github.io/chalk/doc/chalk_engine/forest/struct.Forest.html +[`Forest`]: https://rust-lang.github.io/chalk/doc/chalk_engine/forest/struct.Forest.html ### Walkthrough @@ -150,7 +150,7 @@ is the subgoal after the turnstile (`:-`) that we are currently trying to prove in this strand. Initally, when a strand is first created, there is no selected subgoal. -[`ExClause`]: https://rust-lang-nursery.github.io/chalk/doc/chalk_engine/struct.ExClause.html +[`ExClause`]: https://rust-lang.github.io/chalk/doc/chalk_engine/struct.ExClause.html **Activating a strand.** Now that we have created the table T0 and initialized it with strands, we have to actually try and produce an answer. @@ -187,7 +187,7 @@ Here, we write `selected(L, An)` to indicate that (a) the literal `L` is the selected subgoal and (b) which answer `An` we are looking for. We start out looking for `A0`. -[`ensure_root_answer`]: https://rust-lang-nursery.github.io/chalk/doc/chalk_engine/forest/struct.Forest.html#method.ensure_root_answer +[`ensure_root_answer`]: https://rust-lang.github.io/chalk/doc/chalk_engine/forest/struct.Forest.html#method.ensure_root_answer **Processing the selected subgoal.** Next, we have to try and find an answer to this selected goal. To do that, we will u-canonicalize it @@ -297,6 +297,6 @@ more answers later on. - [Negative Reasoning in Chalk][negative-reasoning-blog] explains the need for negative reasoning, but not how the SLG solver does it -[readme]: https://github.com/rust-lang-nursery/chalk/blob/239e4ae4e69b2785b5f99e0f2b41fc16b0b4e65e/chalk-engine/src/README.md +[readme]: https://github.com/rust-lang/chalk/blob/239e4ae4e69b2785b5f99e0f2b41fc16b0b4e65e/chalk-engine/src/README.md [slg-blog]: http://smallcultfollowing.com/babysteps/blog/2018/01/31/an-on-demand-slg-solver-for-chalk/ [negative-reasoning-blog]: http://aturon.github.io/blog/2017/04/24/negative-chalk/ From e8370fda838fc29feed244d44e887b0fb613db85 Mon Sep 17 00:00:00 2001 From: Mark Mansi Date: Fri, 15 Mar 2019 17:25:12 -0500 Subject: [PATCH 2/3] update rustc driver chapters --- src/SUMMARY.md | 2 +- src/appendix/code-index.md | 7 ++-- src/appendix/stupid-stats.md | 16 +++++---- src/rustc-driver.md | 63 +++++++++++------------------------- 4 files changed, 32 insertions(+), 56 deletions(-) diff --git a/src/SUMMARY.md b/src/SUMMARY.md index 6cd75c588..d3cef1a25 100644 --- a/src/SUMMARY.md +++ b/src/SUMMARY.md @@ -26,7 +26,7 @@ - [Part 2: How rustc works](./part-2-intro.md) - [High-level overview of the compiler source](./high-level-overview.md) -- [The Rustc Driver](./rustc-driver.md) +- [The Rustc Driver and Interface](./rustc-driver.md) - [Rustdoc](./rustdoc.md) - [Queries: demand-driven compilation](./query.md) - [The Query Evaluation Model in Detail](./queries/query-evaluation-model-in-detail.md) diff --git a/src/appendix/code-index.md b/src/appendix/code-index.md index c0a1d03a9..3c71d6bba 100644 --- a/src/appendix/code-index.md +++ b/src/appendix/code-index.md @@ -7,7 +7,7 @@ compiler. Item | Kind | Short description | Chapter | Declaration ----------------|----------|-----------------------------|--------------------|------------------- `BodyId` | struct | One of four types of HIR node identifiers | [Identifiers in the HIR] | [src/librustc/hir/mod.rs](https://doc.rust-lang.org/nightly/nightly-rustc/rustc/hir/struct.BodyId.html) -`CompileState` | struct | State that is passed to a callback at each compiler pass | [The Rustc Driver] | [src/librustc_driver/driver.rs](https://doc.rust-lang.org/nightly/nightly-rustc/rustc_driver/driver/struct.CompileState.html) +`Compiler` | struct | Represents a compiler session and can be used to drive a compilation. | [The Rustc Driver and Interface] | [src/librustc_interface/interface.rs](https://doc.rust-lang.org/nightly/nightly-rustc/rustc_interface/interface/struct.Compiler.html) `ast::Crate` | struct | A syntax-level representation of a parsed crate | [The parser] | [src/librustc/hir/mod.rs](https://doc.rust-lang.org/nightly/nightly-rustc/syntax/ast/struct.Crate.html) `hir::Crate` | struct | A more abstract, compiler-friendly form of a crate's AST | [The Hir] | [src/librustc/hir/mod.rs](https://doc.rust-lang.org/nightly/nightly-rustc/rustc/hir/struct.Crate.html) `DefId` | struct | One of four types of HIR node identifiers | [Identifiers in the HIR] | [src/librustc/hir/def_id.rs](https://doc.rust-lang.org/nightly/nightly-rustc/rustc/hir/def_id/struct.DefId.html) @@ -18,8 +18,9 @@ Item | Kind | Short description | Chapter | `P` | struct | An owned immutable smart pointer. By contrast, `&T` is not owned, and `Box` is not immutable. | None | [src/syntax/ptr.rs](https://doc.rust-lang.org/nightly/nightly-rustc/syntax/ptr/struct.P.html) `ParamEnv` | struct | Information about generic parameters or `Self`, useful for working with associated or generic items | [Parameter Environment] | [src/librustc/ty/mod.rs](https://doc.rust-lang.org/nightly/nightly-rustc/rustc/ty/struct.ParamEnv.html) `ParseSess` | struct | This struct contains information about a parsing session | [The parser] | [src/libsyntax/parse/mod.rs](https://doc.rust-lang.org/nightly/nightly-rustc/syntax/parse/struct.ParseSess.html) +`Query` | struct | Represents the result of query to the `Compiler` interface and allows stealing, borrowing, and returning the results of compiler passes. | [The Rustc Driver and Interface] | [src/librustc_interface/queries.rs](https://doc.rust-lang.org/nightly/nightly-rustc/rustc_interface/queries/struct.Query.html) `Rib` | struct | Represents a single scope of names | [Name resolution] | [src/librustc_resolve/lib.rs](https://doc.rust-lang.org/nightly/nightly-rustc/rustc_resolve/struct.Rib.html) -`Session` | struct | The data associated with a compilation session | [The parser], [The Rustc Driver] | [src/librustc/session/mod.html](https://doc.rust-lang.org/nightly/nightly-rustc/rustc/session/struct.Session.html) +`Session` | struct | The data associated with a compilation session | [The parser], [The Rustc Driver and Interface] | [src/librustc/session/mod.html](https://doc.rust-lang.org/nightly/nightly-rustc/rustc/session/struct.Session.html) `SourceFile` | struct | Part of the `SourceMap`. Maps AST nodes to their source code for a single source file. Was previously called FileMap | [The parser] | [src/libsyntax_pos/lib.rs](https://doc.rust-lang.org/nightly/nightly-rustc/syntax/source_map/struct.SourceFile.html) `SourceMap` | struct | Maps AST nodes to their source code. It is composed of `SourceFile`s. Was previously called CodeMap | [The parser] | [src/libsyntax/source_map.rs](https://doc.rust-lang.org/nightly/nightly-rustc/syntax/source_map/struct.SourceMap.html) `Span` | struct | A location in the user's source code, used for error reporting primarily | [Emitting Diagnostics] | [src/libsyntax_pos/span_encoding.rs](https://doc.rust-lang.org/nightly/nightly-rustc/syntax_pos/struct.Span.html) @@ -33,7 +34,7 @@ Item | Kind | Short description | Chapter | [The HIR]: ../hir.html [Identifiers in the HIR]: ../hir.html#hir-id [The parser]: ../the-parser.html -[The Rustc Driver]: ../rustc-driver.html +[The Rustc Driver and Interface]: ../rustc-driver.html [Type checking]: ../type-checking.html [The `ty` modules]: ../ty.html [Rustdoc]: ../rustdoc.html diff --git a/src/appendix/stupid-stats.md b/src/appendix/stupid-stats.md index a36cac42b..5066973a9 100644 --- a/src/appendix/stupid-stats.md +++ b/src/appendix/stupid-stats.md @@ -1,9 +1,12 @@ # Appendix A: A tutorial on creating a drop-in replacement for rustc > **Note:** This is a copy of `@nrc`'s amazing [stupid-stats]. You should find -> a copy of the code on the GitHub repository although due to the compiler's -> constantly evolving nature, there is no guarantee it'll compile on the first -> go. +> a copy of the code on the GitHub repository. +> +> Due to the compiler's constantly evolving nature, the `rustc_driver` +> mechanisms described in this chapter have been replaced by a new +> [`rustc_interface`] crate. See [The Rustc Driver and Interface] for more +> information. Many tools benefit from being a drop-in replacement for a compiler. By this, I mean that any user of the tool can use `mytool` in all the ways they would @@ -92,7 +95,7 @@ translation). > and [`librustc_codegen_utils`](https://doc.rust-lang.org/nightly/nightly-rustc/rustc_codegen_utils/index.html). All these phases are coordinated by the driver. To see the exact sequence, look -at [the `compile_input` function in `librustc_driver`][compile-input]. +at the `compile_input` function in `librustc_driver`. The driver handles all the highest level coordination of compilation - 1. handling command-line arguments 2. maintaining compilation state (primarily in the `Session`) @@ -101,9 +104,6 @@ The driver handles all the highest level coordination of compilation - To create a drop-in compiler replacement or a compiler replacement, we leave most of compilation alone and customise the driver using its APIs. -[compile-input]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_driver/driver/fn.compile_input.html - - ## The driver customisation APIs There are two primary ways to customise compilation - high level control of the @@ -410,3 +410,5 @@ internally (I already changed save-analysis to use `CompilerController`). I've been experimenting with a prototype rustfmt which also uses these APIs. [stupid-stats]: https://github.com/nrc/stupid-stats +[`rustc_interface`]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_interface/index.html +[The Rustc Driver and Interface]: ../rustc-driver.html diff --git a/src/rustc-driver.md b/src/rustc-driver.md index 397949836..92754f675 100644 --- a/src/rustc-driver.md +++ b/src/rustc-driver.md @@ -1,46 +1,25 @@ -# The Rustc Driver +# The Rustc Driver and 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, -managing state such as the [`SourceMap`] \(maps AST nodes to source code), -[`Session`] \(general build context and error messaging) and the [`TyCtxt`] -\(the "typing context", allowing you to query the type system and other cool -stuff). The `rustc_driver` crate also provides external users with a method +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 -analysing a crate or emulating the compiler in-process (e.g. the RLS). - -For those using `rustc` as a library, the `run_compiler()` function is the main -entrypoint to the compiler. Its main parameters are a list of command-line -arguments and a reference to something which implements the `CompilerCalls` -trait. A `CompilerCalls` creates the overall `CompileController`, letting it -govern which compiler passes are run and attach callbacks to be fired at the end -of each phase. - -From `rustc_driver`'s perspective, the main phases of the compiler are: - -1. *Parse Input:* Initial crate parsing -2. *Configure and Expand:* Resolve `#[cfg]` attributes, name resolution, and - expand macros -3. *Run Analysis Passes:* Run trait resolution, typechecking, region checking - and other miscellaneous analysis passes on the crate -4. *Translate to LLVM:* Translate to the in-memory form of LLVM IR and turn it - into an executable/object files +analysing a crate or emulating the compiler in-process (e.g. the RLS or rustdoc). -The `CompileController` then gives users the ability to inspect the ongoing -compilation process +For those using `rustc` as a library, the `interface::run_compiler()` 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. -- after parsing -- after AST expansion -- after HIR lowering -- after analysis, and -- when compilation is done - -The `CompileState`'s various `state_after_*()` constructors can be inspected to -determine what bits of information are available to which callback. - -For a more detailed explanation on using `rustc_driver`, check out the -[stupid-stats] guide by `@nrc` (attached as [Appendix A]). +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 +`interface::run_compiler`). The `rustc_driver::run_compiler` function takes a bunch of +command-line args and some other configurations and drives the compilation to completion. > **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. @@ -54,21 +33,15 @@ manifests itself in the way people can plug into the compiler, preferring a "push"-style API (callbacks) instead of the more Rust-ic "pull" style (think the `Iterator` trait). -For example the [`CompileState`], the state passed to callbacks after each -phase, is essentially just a box of optional references to pieces inside the -compiler. The lifetime bound on the `CompilerCalls` trait then helps to ensure -compiler internals don't "escape" the compiler (e.g. if you tried to keep a -reference to the AST after the compiler is finished), while still letting users -record *some* state for use after the `run_compiler()` function finishes. - Thread-local storage and interning are used a lot through the compiler to reduce duplication while also preventing a lot of the ergonomic issues due to many pervasive lifetimes. The `rustc::ty::tls` module is used to access these thread-locals, although you should rarely need to touch it. - +[rd_rc]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_driver/fn.run_compiler.html +[`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/ -[`CompileState`]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_driver/driver/struct.CompileState.html +[`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/ty/struct.TyCtxt.html [`SourceMap`]: https://doc.rust-lang.org/nightly/nightly-rustc/syntax/source_map/struct.SourceMap.html From 5c827ef97b91f3bd90cfae9438abf1cc261bb188 Mon Sep 17 00:00:00 2001 From: mark Date: Tue, 19 Mar 2019 19:02:59 -0500 Subject: [PATCH 3/3] address Zoxc's comments --- src/appendix/stupid-stats.md | 5 ++++- src/rustc-driver.md | 8 ++++++++ 2 files changed, 12 insertions(+), 1 deletion(-) diff --git a/src/appendix/stupid-stats.md b/src/appendix/stupid-stats.md index 5066973a9..6ed7d1cbd 100644 --- a/src/appendix/stupid-stats.md +++ b/src/appendix/stupid-stats.md @@ -4,7 +4,9 @@ > a copy of the code on the GitHub repository. > > Due to the compiler's constantly evolving nature, the `rustc_driver` -> mechanisms described in this chapter have been replaced by a new +> mechanisms described in this chapter have changed. In particular, the +> `CompilerCalls` and `CompileController` types have been replaced by +> [`Callbacks`][cb]. Also, there is a new query-based interface in the > [`rustc_interface`] crate. See [The Rustc Driver and Interface] for more > information. @@ -409,6 +411,7 @@ analysis, rather than doing its own analysis). Other parts of the compiler internally (I already changed save-analysis to use `CompilerController`). I've been experimenting with a prototype rustfmt which also uses these APIs. +[cb]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_driver/trait.Callbacks.html [stupid-stats]: https://github.com/nrc/stupid-stats [`rustc_interface`]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_interface/index.html [The Rustc Driver and Interface]: ../rustc-driver.html diff --git a/src/rustc-driver.md b/src/rustc-driver.md index 92754f675..715e6295d 100644 --- a/src/rustc-driver.md +++ b/src/rustc-driver.md @@ -21,6 +21,13 @@ specifically the [`rustc_driver::run_compiler` function][rd_rc] (not to be confu `interface::run_compiler`). 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]. In the past, when +the `rustc_driver::run_compiler` was the primary way to use the compiler as a +library, these callbacks were used to have some custom code run after different +phases of the compilation. If you read [Appendix A], you may notice the use of the +types `CompilerCalls` and `CompileController`, which no longer exist. `Callbacks` +replaces this functionality. + > **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. @@ -38,6 +45,7 @@ duplication while also preventing a lot of the ergonomic issues due to many pervasive lifetimes. The `rustc::ty::tls` module is used to access these thread-locals, although you should rarely need to touch it. +[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/fn.run_compiler.html [`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/