Skip to content

Commit 07b4c15

Browse files
ZoxcZoxc
authored
Merge pull request #288 from mark-i-m/fix-links
Fix links
2 parents e627f50 + 5c827ef commit 07b4c15

File tree

6 files changed

+81
-94
lines changed

6 files changed

+81
-94
lines changed

‎src/SUMMARY.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -26,7 +26,7 @@
2626

2727
- [Part 2: How rustc works](./part-2-intro.md)
2828
- [High-level overview of the compiler source](./high-level-overview.md)
29-
- [The Rustc Driver](./rustc-driver.md)
29+
- [The Rustc Driver and Interface](./rustc-driver.md)
3030
- [Rustdoc](./rustdoc.md)
3131
- [Queries: demand-driven compilation](./query.md)
3232
- [The Query Evaluation Model in Detail](./queries/query-evaluation-model-in-detail.md)

‎src/appendix/code-index.md

Lines changed: 4 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -7,7 +7,7 @@ compiler.
77
Item | Kind | Short description | Chapter | Declaration
88
----------------|----------|-----------------------------|--------------------|-------------------
99
`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)
10-
`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)
10+
`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)
1111
`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)
1212
`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)
1313
`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 |
1818
`P` | struct | An owned immutable smart pointer. By contrast, `&T` is not owned, and `Box<T>` is not immutable. | None | [src/syntax/ptr.rs](https://doc.rust-lang.org/nightly/nightly-rustc/syntax/ptr/struct.P.html)
1919
`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)
2020
`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)
21+
`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)
2122
`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)
22-
`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)
23+
`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)
2324
`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)
2425
`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)
2526
`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 |
3334
[The HIR]: ../hir.html
3435
[Identifiers in the HIR]: ../hir.html#hir-id
3536
[The parser]: ../the-parser.html
36-
[The Rustc Driver]: ../rustc-driver.html
37+
[The Rustc Driver and Interface]: ../rustc-driver.html
3738
[Type checking]: ../type-checking.html
3839
[The `ty` modules]: ../ty.html
3940
[Rustdoc]: ../rustdoc.html

‎src/appendix/stupid-stats.md

Lines changed: 12 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -1,9 +1,14 @@
11
# Appendix A: A tutorial on creating a drop-in replacement for rustc
22

33
> **Note:** This is a copy of `@nrc`'s amazing [stupid-stats]. You should find
4-
> a copy of the code on the GitHub repository although due to the compiler's
5-
> constantly evolving nature, there is no guarantee it'll compile on the first
6-
> go.
4+
> a copy of the code on the GitHub repository.
5+
>
6+
> Due to the compiler's constantly evolving nature, the `rustc_driver`
7+
> mechanisms described in this chapter have changed. In particular, the
8+
> `CompilerCalls` and `CompileController` types have been replaced by
9+
> [`Callbacks`][cb]. Also, there is a new query-based interface in the
10+
> [`rustc_interface`] crate. See [The Rustc Driver and Interface] for more
11+
> information.
712
813
Many tools benefit from being a drop-in replacement for a compiler. By this, I
914
mean that any user of the tool can use `mytool` in all the ways they would
@@ -92,7 +97,7 @@ translation).
9297
> and [`librustc_codegen_utils`](https://doc.rust-lang.org/nightly/nightly-rustc/rustc_codegen_utils/index.html).
9398
9499
All these phases are coordinated by the driver. To see the exact sequence, look
95-
at [the `compile_input` function in `librustc_driver`][compile-input].
100+
at the `compile_input` function in `librustc_driver`.
96101
The driver handles all the highest level coordination of compilation -
97102
1. handling command-line arguments
98103
2. maintaining compilation state (primarily in the `Session`)
@@ -101,9 +106,6 @@ The driver handles all the highest level coordination of compilation -
101106
To create a drop-in compiler replacement or a compiler replacement,
102107
we leave most of compilation alone and customise the driver using its APIs.
103108

104-
[compile-input]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_driver/driver/fn.compile_input.html
105-
106-
107109
## The driver customisation APIs
108110

109111
There are two primary ways to customise compilation - high level control of the
@@ -409,4 +411,7 @@ analysis, rather than doing its own analysis). Other parts of the compiler
409411
internally (I already changed save-analysis to use `CompilerController`). I've
410412
been experimenting with a prototype rustfmt which also uses these APIs.
411413

414+
[cb]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_driver/trait.Callbacks.html
412415
[stupid-stats]: https://github.com/nrc/stupid-stats
416+
[`rustc_interface`]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_interface/index.html
417+
[The Rustc Driver and Interface]: ../rustc-driver.html

‎src/rustc-driver.md

Lines changed: 28 additions & 47 deletions
Original file line numberDiff line numberDiff line change
@@ -1,46 +1,32 @@
1-
# The Rustc Driver
1+
# The Rustc Driver and Interface
22

33
The [`rustc_driver`] is essentially `rustc`'s `main()` function. It acts as
44
the glue for running the various phases of the compiler in the correct order,
5-
managing state such as the [`SourceMap`] \(maps AST nodes to source code),
6-
[`Session`] \(general build context and error messaging) and the [`TyCtxt`]
7-
\(the "typing context", allowing you to query the type system and other cool
8-
stuff). The `rustc_driver` crate also provides external users with a method
5+
using the interface defined in the [`rustc_interface`] crate.
6+
7+
The `rustc_interface` crate provides external users with an (unstable) API
98
for running code at particular times during the compilation process, allowing
109
third parties to effectively use `rustc`'s internals as a library for
11-
analysing a crate or emulating the compiler in-process (e.g. the RLS).
12-
13-
For those using `rustc` as a library, the `run_compiler()` function is the main
14-
entrypoint to the compiler. Its main parameters are a list of command-line
15-
arguments and a reference to something which implements the `CompilerCalls`
16-
trait. A `CompilerCalls` creates the overall `CompileController`, letting it
17-
govern which compiler passes are run and attach callbacks to be fired at the end
18-
of each phase.
19-
20-
From `rustc_driver`'s perspective, the main phases of the compiler are:
21-
22-
1. *Parse Input:* Initial crate parsing
23-
2. *Configure and Expand:* Resolve `#[cfg]` attributes, name resolution, and
24-
expand macros
25-
3. *Run Analysis Passes:* Run trait resolution, typechecking, region checking
26-
and other miscellaneous analysis passes on the crate
27-
4. *Translate to LLVM:* Translate to the in-memory form of LLVM IR and turn it
28-
into an executable/object files
29-
30-
The `CompileController` then gives users the ability to inspect the ongoing
31-
compilation process
32-
33-
- after parsing
34-
- after AST expansion
35-
- after HIR lowering
36-
- after analysis, and
37-
- when compilation is done
38-
39-
The `CompileState`'s various `state_after_*()` constructors can be inspected to
40-
determine what bits of information are available to which callback.
41-
42-
For a more detailed explanation on using `rustc_driver`, check out the
43-
[stupid-stats] guide by `@nrc` (attached as [Appendix A]).
10+
analysing a crate or emulating the compiler in-process (e.g. the RLS or rustdoc).
11+
12+
For those using `rustc` as a library, the `interface::run_compiler()` function is the main
13+
entrypoint to the compiler. It takes a configuration for the compiler and a closure that
14+
takes a [`Compiler`]. `run_compiler` creates a `Compiler` from the configuration and passes
15+
it to the closure. Inside the closure, you can use the `Compiler` to drive queries to compile
16+
a crate and get the results. This is what the `rustc_driver` does too.
17+
18+
You can see what queries are currently available through the rustdocs for [`Compiler`].
19+
You can see an example of how to use them by looking at the `rustc_driver` implementation,
20+
specifically the [`rustc_driver::run_compiler` function][rd_rc] (not to be confused with
21+
`interface::run_compiler`). The `rustc_driver::run_compiler` function takes a bunch of
22+
command-line args and some other configurations and drives the compilation to completion.
23+
24+
`rustc_driver::run_compiler` also takes a [`Callbacks`][cb]. In the past, when
25+
the `rustc_driver::run_compiler` was the primary way to use the compiler as a
26+
library, these callbacks were used to have some custom code run after different
27+
phases of the compilation. If you read [Appendix A], you may notice the use of the
28+
types `CompilerCalls` and `CompileController`, which no longer exist. `Callbacks`
29+
replaces this functionality.
4430

4531
> **Warning:** By its very nature, the internal compiler APIs are always going
4632
> to be unstable. That said, we do try not to break things unnecessarily.
@@ -54,21 +40,16 @@ manifests itself in the way people can plug into the compiler, preferring a
5440
"push"-style API (callbacks) instead of the more Rust-ic "pull" style (think
5541
the `Iterator` trait).
5642

57-
For example the [`CompileState`], the state passed to callbacks after each
58-
phase, is essentially just a box of optional references to pieces inside the
59-
compiler. The lifetime bound on the `CompilerCalls` trait then helps to ensure
60-
compiler internals don't "escape" the compiler (e.g. if you tried to keep a
61-
reference to the AST after the compiler is finished), while still letting users
62-
record *some* state for use after the `run_compiler()` function finishes.
63-
6443
Thread-local storage and interning are used a lot through the compiler to reduce
6544
duplication while also preventing a lot of the ergonomic issues due to many
6645
pervasive lifetimes. The `rustc::ty::tls` module is used to access these
6746
thread-locals, although you should rarely need to touch it.
6847

69-
48+
[cb]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_driver/trait.Callbacks.html
49+
[rd_rc]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_driver/fn.run_compiler.html
50+
[`rustc_interface`]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_interface/index.html
7051
[`rustc_driver`]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_driver/
71-
[`CompileState`]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_driver/driver/struct.CompileState.html
52+
[`Compiler`]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_interface/interface/struct.Compiler.html
7253
[`Session`]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc/session/struct.Session.html
7354
[`TyCtxt`]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc/ty/struct.TyCtxt.html
7455
[`SourceMap`]: https://doc.rust-lang.org/nightly/nightly-rustc/syntax/source_map/struct.SourceMap.html

‎src/traits/chalk-overview.md

Lines changed: 32 additions & 32 deletions
Original file line numberDiff line numberDiff line change
@@ -172,7 +172,7 @@ Chalk's functionality is broken up into the following crates:
172172
- `coherence`, which implements coherence rules
173173
- Also includes [chalki][chalki], chalk's REPL.
174174

175-
[Browse source code on GitHub](https://github.com/rust-lang-nursery/chalk)
175+
[Browse source code on GitHub](https://github.com/rust-lang/chalk)
176176

177177
## Testing
178178

@@ -202,8 +202,8 @@ Likewise, lowering tests use the [`lowering_success!` and
202202

203203
## More Resources
204204

205-
* [Chalk Source Code](https://github.com/rust-lang-nursery/chalk)
206-
* [Chalk Glossary](https://github.com/rust-lang-nursery/chalk/blob/master/GLOSSARY.md)
205+
* [Chalk Source Code](https://github.com/rust-lang/chalk)
206+
* [Chalk Glossary](https://github.com/rust-lang/chalk/blob/master/GLOSSARY.md)
207207

208208
### Blog Posts
209209

@@ -224,34 +224,34 @@ Likewise, lowering tests use the [`lowering_success!` and
224224
[wf-checking]: ./wf.html
225225

226226
[ast]: https://en.wikipedia.org/wiki/Abstract_syntax_tree
227-
[chalk]: https://github.com/rust-lang-nursery/chalk
228-
[rustc-issues]: https://github.com/rust-lang-nursery/rustc-guide/issues
227+
[chalk]: https://github.com/rust-lang/chalk
228+
[rustc-issues]: https://github.com/rust-lang/rustc-guide/issues
229229
[universal quantification]: https://en.wikipedia.org/wiki/Universal_quantification
230230

231-
[`ProgramClause`]: https://rust-lang-nursery.github.io/chalk/doc/chalk_ir/enum.ProgramClause.html
232-
[`ProgramEnvironment`]: https://rust-lang-nursery.github.io/chalk/doc/chalk_ir/struct.ProgramEnvironment.html
233-
[chalk_engine]: https://rust-lang-nursery.github.io/chalk/doc/chalk_engine/index.html
234-
[chalk_ir]: https://rust-lang-nursery.github.io/chalk/doc/chalk_ir/index.html
235-
[chalk_parse]: https://rust-lang-nursery.github.io/chalk/doc/chalk_parse/index.html
236-
[chalk_solve]: https://rust-lang-nursery.github.io/chalk/doc/chalk_solve/index.html
237-
[doc-chalk]: https://rust-lang-nursery.github.io/chalk/doc/chalk/index.html
238-
[engine-context]: https://rust-lang-nursery.github.io/chalk/doc/chalk_engine/context/index.html
239-
[rust_ir-program]: https://rust-lang-nursery.github.io/chalk/doc/chalk/rust_ir/struct.Program.html
240-
[rust_ir]: https://rust-lang-nursery.github.io/chalk/doc/chalk/rust_ir/index.html
241-
242-
[binders-struct]: https://github.com/rust-lang-nursery/chalk/blob/94a1941a021842a5fcb35cd043145c8faae59f08/src/ir.rs#L661
243-
[chalk-ast]: https://github.com/rust-lang-nursery/chalk/blob/master/chalk-parse/src/ast.rs
244-
[chalk-test-example]: https://github.com/rust-lang-nursery/chalk/blob/4bce000801de31bf45c02f742a5fce335c9f035f/src/test.rs#L115
245-
[chalk-test-lowering-example]: https://github.com/rust-lang-nursery/chalk/blob/4bce000801de31bf45c02f742a5fce335c9f035f/src/rust_ir/lowering/test.rs#L8-L31
246-
[chalk-test-lowering]: https://github.com/rust-lang-nursery/chalk/blob/4bce000801de31bf45c02f742a5fce335c9f035f/src/rust_ir/lowering/test.rs
247-
[chalk-test-wf]: https://github.com/rust-lang-nursery/chalk/blob/4bce000801de31bf45c02f742a5fce335c9f035f/src/rules/wf/test.rs#L1
248-
[chalki]: https://rust-lang-nursery.github.io/chalk/doc/chalki/index.html
249-
[clause]: https://github.com/rust-lang-nursery/chalk/blob/master/GLOSSARY.md#clause
250-
[coherence-src]: https://github.com/rust-lang-nursery/chalk/blob/master/src/coherence.rs
251-
[ir-code]: https://github.com/rust-lang-nursery/chalk/blob/master/src/rust_ir.rs
252-
[rules-environment]: https://github.com/rust-lang-nursery/chalk/blob/94a1941a021842a5fcb35cd043145c8faae59f08/src/rules.rs#L9
253-
[rules-src]: https://github.com/rust-lang-nursery/chalk/blob/4bce000801de31bf45c02f742a5fce335c9f035f/src/rules.rs
254-
[rules-wf-src]: https://github.com/rust-lang-nursery/chalk/blob/4bce000801de31bf45c02f742a5fce335c9f035f/src/rules/wf.rs
255-
[solve_goal]: https://github.com/rust-lang-nursery/chalk/blob/4bce000801de31bf45c02f742a5fce335c9f035f/src/test.rs#L85
256-
[test-lowering-macros]: https://github.com/rust-lang-nursery/chalk/blob/4bce000801de31bf45c02f742a5fce335c9f035f/src/test_util.rs#L21-L54
257-
[test-macro]: https://github.com/rust-lang-nursery/chalk/blob/4bce000801de31bf45c02f742a5fce335c9f035f/src/test.rs#L33
231+
[`ProgramClause`]: https://rust-lang.github.io/chalk/doc/chalk_ir/enum.ProgramClause.html
232+
[`ProgramEnvironment`]: https://rust-lang.github.io/chalk/doc/chalk_ir/struct.ProgramEnvironment.html
233+
[chalk_engine]: https://rust-lang.github.io/chalk/doc/chalk_engine/index.html
234+
[chalk_ir]: https://rust-lang.github.io/chalk/doc/chalk_ir/index.html
235+
[chalk_parse]: https://rust-lang.github.io/chalk/doc/chalk_parse/index.html
236+
[chalk_solve]: https://rust-lang.github.io/chalk/doc/chalk_solve/index.html
237+
[doc-chalk]: https://rust-lang.github.io/chalk/doc/chalk/index.html
238+
[engine-context]: https://rust-lang.github.io/chalk/doc/chalk_engine/context/index.html
239+
[rust_ir-program]: https://rust-lang.github.io/chalk/doc/chalk/rust_ir/struct.Program.html
240+
[rust_ir]: https://rust-lang.github.io/chalk/doc/chalk/rust_ir/index.html
241+
242+
[binders-struct]: https://github.com/rust-lang/chalk/blob/94a1941a021842a5fcb35cd043145c8faae59f08/src/ir.rs#L661
243+
[chalk-ast]: https://github.com/rust-lang/chalk/blob/master/chalk-parse/src/ast.rs
244+
[chalk-test-example]: https://github.com/rust-lang/chalk/blob/4bce000801de31bf45c02f742a5fce335c9f035f/src/test.rs#L115
245+
[chalk-test-lowering-example]: https://github.com/rust-lang/chalk/blob/4bce000801de31bf45c02f742a5fce335c9f035f/src/rust_ir/lowering/test.rs#L8-L31
246+
[chalk-test-lowering]: https://github.com/rust-lang/chalk/blob/4bce000801de31bf45c02f742a5fce335c9f035f/src/rust_ir/lowering/test.rs
247+
[chalk-test-wf]: https://github.com/rust-lang/chalk/blob/4bce000801de31bf45c02f742a5fce335c9f035f/src/rules/wf/test.rs#L1
248+
[chalki]: https://rust-lang.github.io/chalk/doc/chalki/index.html
249+
[clause]: https://github.com/rust-lang/chalk/blob/master/GLOSSARY.md#clause
250+
[coherence-src]: https://github.com/rust-lang/chalk/blob/master/src/coherence.rs
251+
[ir-code]: https://github.com/rust-lang/chalk/blob/master/src/rust_ir.rs
252+
[rules-environment]: https://github.com/rust-lang/chalk/blob/94a1941a021842a5fcb35cd043145c8faae59f08/src/rules.rs#L9
253+
[rules-src]: https://github.com/rust-lang/chalk/blob/4bce000801de31bf45c02f742a5fce335c9f035f/src/rules.rs
254+
[rules-wf-src]: https://github.com/rust-lang/chalk/blob/4bce000801de31bf45c02f742a5fce335c9f035f/src/rules/wf.rs
255+
[solve_goal]: https://github.com/rust-lang/chalk/blob/4bce000801de31bf45c02f742a5fce335c9f035f/src/test.rs#L85
256+
[test-lowering-macros]: https://github.com/rust-lang/chalk/blob/4bce000801de31bf45c02f742a5fce335c9f035f/src/test_util.rs#L21-L54
257+
[test-macro]: https://github.com/rust-lang/chalk/blob/4bce000801de31bf45c02f742a5fce335c9f035f/src/test.rs#L33

0 commit comments

Comments
 (0)