Skip to content

Fix links #288

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
merged 3 commits into from
Mar 20, 2019
Merged

Fix links #288

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
4013f45
chalk has moved to rust-lang
mark-i-m Mar 15, 2019
e8370fd
update rustc driver chapters
mark-i-m Mar 15, 2019
5c827ef
address Zoxc's comments
mark-i-m Mar 20, 2019
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 1 addition & 1 deletion src/SUMMARY.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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)
Expand Down
7 changes: 4 additions & 3 deletions src/appendix/code-index.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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)
Expand All @@ -18,8 +18,9 @@ Item | Kind | Short description | Chapter |
`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)
`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)
Expand All @@ -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
Expand Down
19 changes: 12 additions & 7 deletions src/appendix/stupid-stats.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,9 +1,14 @@
# 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 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.

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
Expand Down Expand Up @@ -92,7 +97,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`)
Expand All @@ -101,9 +106,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
Expand Down Expand Up @@ -409,4 +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
75 changes: 28 additions & 47 deletions src/rustc-driver.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,46 +1,32 @@
# 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

The `CompileController` then gives users the ability to inspect the ongoing
compilation process

- 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]).
analysing a crate or emulating the compiler in-process (e.g. the RLS or rustdoc).

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.

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.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Maybe mention that rustc_driver::run_compiler takes a Callbacks type, which essentially replaces CompilerCalls + CompileController?


`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.
Expand All @@ -54,21 +40,16 @@ 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.


[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/
[`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
Expand Down
64 changes: 32 additions & 32 deletions src/traits/chalk-overview.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down Expand Up @@ -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

Expand All @@ -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
Loading