From 30b6be0f7d173bb2b786c5f4e77f64ca29fff621 Mon Sep 17 00:00:00 2001 From: Mark Mansi Date: Wed, 23 May 2018 12:13:46 -0500 Subject: [PATCH] first round of link fixes --- src/SUMMARY.md | 52 ++++++++++++++++----------------- src/rustc-driver.md | 22 +++++++------- src/traits/caching.md | 4 +-- src/traits/canonical-queries.md | 6 ++-- src/traits/canonicalization.md | 6 ++-- src/traits/goals-and-clauses.md | 13 +++++---- src/traits/index.md | 12 ++++---- src/traits/lowering-module.md | 2 +- src/traits/lowering-rules.md | 10 +++---- src/traits/lowering-to-logic.md | 4 +-- src/traits/resolution.md | 2 +- src/type-inference.md | 2 +- 12 files changed, 68 insertions(+), 67 deletions(-) diff --git a/src/SUMMARY.md b/src/SUMMARY.md index 2db3e62c..a2b7d3e1 100644 --- a/src/SUMMARY.md +++ b/src/SUMMARY.md @@ -22,34 +22,34 @@ - [The HIR (High-level IR)](./hir.md) - [The `ty` module: representing types](./ty.md) - [Type inference](./type-inference.md) -- [Trait solving (old-style)](./trait-resolution.md) - - [Higher-ranked trait bounds](./trait-hrtb.md) - - [Caching subtleties](./trait-caching.md) - - [Specialization](./trait-specialization.md) +- [Trait solving (old-style)](./traits/resolution.md) + - [Higher-ranked trait bounds](./traits/hrtb.md) + - [Caching subtleties](./traits/caching.md) + - [Specialization](./traits/specialization.md) - [Trait solving (new-style)](./traits.md) - - [Lowering to logic](./traits-lowering-to-logic.md) - - [Goals and clauses](./traits-goals-and-clauses.md) - - [Equality and associated types](./traits-associated-types.md) - - [Implied bounds](./traits-implied-bounds.md) - - [Region constraints](./traits-regions.md) - - [Canonical queries](./traits-canonical-queries.md) - - [Canonicalization](./traits-canonicalization.md) - - [Lowering rules](./traits-lowering-rules.md) - - [The lowering module in rustc](./traits-lowering-module.md) - - [Well-formedness checking](./traits-wf.md) - - [The SLG solver](./traits-slg.md) + - [Lowering to logic](./traits/lowering-to-logic.md) + - [Goals and clauses](./traits/goals-and-clauses.md) + - [Equality and associated types](./traits/associated-types.md) + - [Implied bounds](./traits/implied-bounds.md) + - [Region constraints](./traits/regions.md) + - [Canonical queries](./traits/canonical-queries.md) + - [Canonicalization](./traits/canonicalization.md) + - [Lowering rules](./traits/lowering-rules.md) + - [The lowering module in rustc](./traits/lowering-module.md) + - [Well-formedness checking](./traits/wf.md) + - [The SLG solver](./traits/slg.md) - [An Overview of Chalk](./chalk-overview.md) - - [Bibliography](./traits-bibliography.md) + - [Bibliography](./traits/bibliography.md) - [Type checking](./type-checking.md) - [Method Lookup](./method-lookup.md) - [Variance](./variance.md) - [The MIR (Mid-level IR)](./mir.md) - - [MIR construction](./mir-construction.md) - - [MIR visitor and traversal](./mir-visitor.md) - - [MIR passes: getting the MIR for a function](./mir-passes.md) - - [MIR borrowck](./mir-borrowck.md) - - [MIR-based region checking (NLL)](./mir-regionck.md) - - [MIR optimizations](./mir-optimizations.md) + - [MIR construction](./mir/construction.md) + - [MIR visitor and traversal](./mir/visitor.md) + - [MIR passes: getting the MIR for a function](./mir/passes.md) + - [MIR borrowck](./mir/borrowck.md) + - [MIR-based region checking (NLL)](./mir/regionck.md) + - [MIR optimizations](./mir/optimizations.md) - [Constant evaluation](./const-eval.md) - [miri const evaluator](./miri.md) - [Parameter Environments](./param_env.md) @@ -58,7 +58,7 @@ --- -- [Appendix A: Stupid Stats](./appendix-stupid-stats.md) -- [Appendix B: Background material](./appendix-background.md) -- [Appendix C: Glossary](./appendix-glossary.md) -- [Appendix D: Code Index](./appendix-code-index.md) +- [Appendix A: Stupid Stats](./appendix/stupid-stats.md) +- [Appendix B: Background material](./appendix/background.md) +- [Appendix C: Glossary](./appendix/glossary.md) +- [Appendix D: Code Index](./appendix/code-index.md) diff --git a/src/rustc-driver.md b/src/rustc-driver.md index af3c3c09..1550b14e 100644 --- a/src/rustc-driver.md +++ b/src/rustc-driver.md @@ -20,14 +20,14 @@ 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 +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 +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 +The `CompileController` then gives users the ability to inspect the ongoing compilation process - after parsing @@ -39,7 +39,7 @@ compilation process 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 +For a more detailed explanation on using `rustc_driver`, check out the [stupid-stats] guide by `@nrc` (attached as [Appendix A]). > **Warning:** By its very nature, the internal compiler APIs are always going @@ -47,23 +47,23 @@ For a more detailed explanation on using `rustc_driver`, check out the ## A Note On Lifetimes -The Rust compiler is a fairly large program containing lots of big data +The Rust compiler is a fairly large program containing lots of big data structures (e.g. the AST, HIR, and the type system) and as such, arenas and -references are heavily relied upon to minimize unnecessary memory use. This +references are heavily relied upon to minimize unnecessary memory use. This 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 +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 +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 +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. @@ -73,4 +73,4 @@ thread-locals, although you should rarely need to touch it. [`TyCtxt`]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc/ty/struct.TyCtxt.html [`CodeMap`]: https://doc.rust-lang.org/nightly/nightly-rustc/syntax/codemap/struct.CodeMap.html [stupid-stats]: https://github.com/nrc/stupid-stats -[Appendix A]: appendix-stupid-stats.html \ No newline at end of file +[Appendix A]: appendix/stupid-stats.html diff --git a/src/traits/caching.md b/src/traits/caching.md index 4b7d7e09..228ff091 100644 --- a/src/traits/caching.md +++ b/src/traits/caching.md @@ -24,7 +24,7 @@ On the other hand, if there is no hit, we need to go through the [selection process] from scratch. Suppose, we come to the conclusion that the only possible impl is this one, with def-id 22: -[selection process]: ./trait-resolution.html#selection +[selection process]: ./traits/resolution.html#selection ```rust,ignore impl Foo for usize { ... } // Impl #22 @@ -34,7 +34,7 @@ We would then record in the cache `usize : Foo<$0> => ImplCandidate(22)`. Next we would [confirm] `ImplCandidate(22)`, which would (as a side-effect) unify `$t` with `isize`. -[confirm]: ./trait-resolution.html#confirmation +[confirm]: ./traits/resolution.html#confirmation Now, at some later time, we might come along and see a `usize : Foo<$u>`. When skolemized, this would yield `usize : Foo<$0>`, just as diff --git a/src/traits/canonical-queries.md b/src/traits/canonical-queries.md index 2737737b..56637dac 100644 --- a/src/traits/canonical-queries.md +++ b/src/traits/canonical-queries.md @@ -7,7 +7,7 @@ would like to know the answer to -- and in the checker or other parts of the system, may in the course of doing their thing want to know whether some trait is implemented for some type (e.g., is `u32: Debug` true?). Or they may want to -[normalize some associated type](./traits-associated-types.html). +[normalize some associated type](./traits/associated-types.html). This section covers queries at a fairly high level of abstraction. The subsections look a bit more closely at how these ideas are implemented @@ -106,7 +106,7 @@ value for a type variable, that means that this is the **only possible instantiation** that you could use, given the current set of impls and where-clauses, that would be provable. (Internally within the solver, though, they can potentially enumerate all possible answers. See -[the description of the SLG solver](./traits-slg.html) for details.) +[the description of the SLG solver](./traits/slg.html) for details.) The response to a trait query in rustc is typically a `Result, NoSolution>` (where the `T` will vary a bit @@ -132,7 +132,7 @@ we did find. It consists of four parts: - **Region constraints:** these are relations that must hold between the lifetimes that you supplied as inputs. We'll ignore these here, but see the - [section on handling regions in traits](./traits-regions.html) for + [section on handling regions in traits](./traits/regions.html) for more details. - **Value:** The query result also comes with a value of type `T`. For some specialized queries -- like normalizing associated types -- diff --git a/src/traits/canonicalization.md b/src/traits/canonicalization.md index fa39151d..37a59026 100644 --- a/src/traits/canonicalization.md +++ b/src/traits/canonicalization.md @@ -16,7 +16,7 @@ starting from zero and numbered in a fixed order (left to right, for the most part, but really it doesn't matter as long as it is consistent). -[cq]: ./traits-canonical-queries.html +[cq]: ./traits/canonical-queries.html So, for example, if we have the type `X = (?T, ?U)`, where `?T` and `?U` are distinct, unbound inference variables, then the canonical @@ -98,12 +98,12 @@ Remember that substitution S though! We're going to need it later. OK, now that we have a fresh inference context and an instantiated query, we can go ahead and try to solve it. The trait solver itself is -explained in more detail in [another section](./traits-slg.html), but +explained in more detail in [another section](./traits/slg.html), but suffice to say that it will compute a [certainty value][cqqr] (`Proven` or `Ambiguous`) and have side-effects on the inference variables we've created. For example, if there were only one impl of `Foo`, like so: -[cqqr]: ./traits-canonical-queries.html#query-response +[cqqr]: ./traits/canonical-queries.html#query-response ```rust,ignore impl<'a, X> Foo<'a, X> for Vec diff --git a/src/traits/goals-and-clauses.md b/src/traits/goals-and-clauses.md index 882f86b8..5844e8d4 100644 --- a/src/traits/goals-and-clauses.md +++ b/src/traits/goals-and-clauses.md @@ -2,7 +2,7 @@ In logic programming terms, a **goal** is something that you must prove and a **clause** is something that you know is true. As -described in the [lowering to logic](./traits-lowering-to-logic.html) +described in the [lowering to logic](./traits/lowering-to-logic.html) chapter, Rust's trait solver is based on an extension of hereditary harrop (HH) clauses, which extend traditional Prolog Horn clauses with a few new superpowers. @@ -37,7 +37,7 @@ paper ["A Proof Procedure for the Logic of Hereditary Harrop Formulas"][pphhf] gives the details. -[pphhf]: ./traits-bibliography.html#pphhf +[pphhf]: ./traits/bibliography.html#pphhf @@ -94,7 +94,7 @@ e.g. `ProjectionEq::Item = u8` The given associated type `Projection` is equal to `Type`; this can be proved with either normalization or using skolemized types. See [the section -on associated types](./traits-associated-types.html). +on associated types](./traits/associated-types.html). #### Normalize(Projection -> Type) e.g. `ProjectionEq::Item -> u8` @@ -102,11 +102,12 @@ e.g. `ProjectionEq::Item -> u8` The given associated type `Projection` can be [normalized][n] to `Type`. As discussed in [the section on associated -types](./traits-associated-types.html), `Normalize` implies `ProjectionEq`, +types](./traits/associated-types.html), `Normalize` implies `ProjectionEq`, but not vice versa. In general, proving `Normalize(::Item -> U)` also requires proving `Implemented(T: Trait)`. -[n]: ./traits-associated-types.html#normalize +[n]: ./traits/associated-types.html#normalize +[at]: ./traits/associated-types.html #### FromEnv(TraitRef), FromEnv(Projection = Type) e.g. `FromEnv(Self: Add)` @@ -211,7 +212,7 @@ In addition to auto traits, `WellFormed` predicates are co-inductive. These are used to achieve a similar "enumerate all the cases" pattern, as described in the section on [implied bounds]. -[implied bounds]: ./traits-lowering-rules.html#implied-bounds +[implied bounds]: ./traits/lowering-rules.html#implied-bounds ## Incomplete chapter diff --git a/src/traits/index.md b/src/traits/index.md index 175e6418..6aad2474 100644 --- a/src/traits/index.md +++ b/src/traits/index.md @@ -13,20 +13,20 @@ instructions for getting involved in the Trait solving is based around a few key ideas: -- [Lowering to logic](./traits-lowering-to-logic.html), which expresses +- [Lowering to logic](./traits/lowering-to-logic.html), which expresses Rust traits in terms of standard logical terms. - - The [goals and clauses](./traits-goals-and-clauses.html) chapter + - The [goals and clauses](./traits/goals-and-clauses.html) chapter describes the precise form of rules we use, and - [lowering rules](./traits-lowering-rules.html) gives the complete set of + [lowering rules](./traits/lowering-rules.html) gives the complete set of lowering rules in a more reference-like form. -- [Canonical queries](./traits-canonical-queries.html), which allow us +- [Canonical queries](./traits/canonical-queries.html), which allow us to solve trait problems (like "is `Foo` implemented for the type `Bar`?") once, and then apply that same result independently in many different inference contexts. -- [Lazy normalization](./traits-associated-types.html), which is the +- [Lazy normalization](./traits/associated-types.html), which is the technique we use to accommodate associated types when figuring out whether types are equal. -- [Region constraints](./traits-regions.html), which are accumulated +- [Region constraints](./traits/regions.html), which are accumulated during trait solving but mostly ignored. This means that trait solving effectively ignores the precise regions involved, always -- but we still remember the constraints on them so that those diff --git a/src/traits/lowering-module.md b/src/traits/lowering-module.md index 08e0b952..205e9a17 100644 --- a/src/traits/lowering-module.md +++ b/src/traits/lowering-module.md @@ -1,7 +1,7 @@ # The lowering module in rustc The program clauses described in the -[lowering rules](./traits-lowering-rules.html) section are actually +[lowering rules](./traits/lowering-rules.html) section are actually created in the [`rustc_traits::lowering`][lowering] module. [lowering]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc_traits/lowering/ diff --git a/src/traits/lowering-rules.md b/src/traits/lowering-rules.md index 06dc6740..f635ee85 100644 --- a/src/traits/lowering-rules.md +++ b/src/traits/lowering-rules.md @@ -4,8 +4,8 @@ This section gives the complete lowering rules for Rust traits into [program clauses][pc]. It is a kind of reference. These rules reference the [domain goals][dg] defined in an earlier section. -[pc]: ./traits-goals-and-clauses.html -[dg]: ./traits-goals-and-clauses.html#domain-goals +[pc]: ./traits/goals-and-clauses.html +[dg]: ./traits/goals-and-clauses.html#domain-goals ## Notation @@ -16,7 +16,7 @@ The nonterminal `Ai` is used to mean some generic *argument*, which might be a lifetime like `'a` or a type like `Vec`. When defining the lowering rules, we will give goals and clauses in -the [notation given in this section](./traits-goals-and-clauses.html). +the [notation given in this section](./traits/goals-and-clauses.html). We sometimes insert "macros" like `LowerWhereClause!` into these definitions; these macros reference other sections within this chapter. @@ -141,7 +141,7 @@ This `WellFormed` rule states that `T: Trait` is well-formed if (a) `T: Trait` is implemented and (b) all the where-clauses declared on `Trait` are well-formed (and hence they are implemented). Remember that the `WellFormed` predicate is -[coinductive](./traits-goals-and-clauses.html#coinductive); in this +[coinductive](./traits/goals-and-clauses.html#coinductive); in this case, it is serving as a kind of "carrier" that allows us to enumerate all the where clauses that are transitively implied by `T: Trait`. @@ -192,7 +192,7 @@ where WC We will produce a number of program clauses. The first two define the rules by which `ProjectionEq` can succeed; these two clauses are discussed -in detail in the [section on associated types](./traits-associated-types.html), +in detail in the [section on associated types](./traits/associated-types.html), but reproduced here for reference: ```text diff --git a/src/traits/lowering-to-logic.md b/src/traits/lowering-to-logic.md index 54b3473d..2de28ce4 100644 --- a/src/traits/lowering-to-logic.md +++ b/src/traits/lowering-to-logic.md @@ -170,8 +170,8 @@ example Gopalan Nadathur's excellent ["A Proof Procedure for the Logic of Hereditary Harrop Formulas"][pphhf] in [the bibliography]. -[the bibliography]: ./traits-bibliography.html -[pphhf]: ./traits-bibliography.html#pphhf +[the bibliography]: ./traits/bibliography.html +[pphhf]: ./traits/bibliography.html#pphhf It turns out that supporting FOHH is not really all that hard. And once we are able to do that, we can easily describe the type-checking diff --git a/src/traits/resolution.md b/src/traits/resolution.md index b9fa81bd..e33e0c8e 100644 --- a/src/traits/resolution.md +++ b/src/traits/resolution.md @@ -6,7 +6,7 @@ some non-obvious things. **Note:** This chapter (and its subchapters) describe how the trait solver **currently** works. However, we are in the process of designing a new trait solver. If you'd prefer to read about *that*, -see [*this* traits chapter](./traits.html). +see [*this* traits chapter](./traits/index.html). ## Major concepts diff --git a/src/type-inference.md b/src/type-inference.md index 9ae88dec..a3d012b5 100644 --- a/src/type-inference.md +++ b/src/type-inference.md @@ -125,7 +125,7 @@ actual return type is not `()`, but rather `InferOk<()>`. The to ensure that these are fulfilled (typically by enrolling them in a fulfillment context). See the [trait chapter] for more background on that. -[trait chapter]: trait-resolution.html +[trait chapter]: traits/resolution.html You can similarly enforce subtyping through `infcx.at(..).sub(..)`. The same basic concepts as above apply.