Skip to content

Commit 40622c7

Browse files
OlingCatOlingCat
committed
Add translation directory
1 parent f53c6a6 commit 40622c7

File tree

92 files changed

+14193
-3
lines changed

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

92 files changed

+14193
-3
lines changed

‎book.toml

+4-3
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,8 @@
11
[book]
2-
title = "Guide to Rustc Development"
3-
author = "Rustc developers"
4-
description = "A guide to developing rustc"
2+
title = "Rustc 开发指南"
3+
author = "Rustc 开发者"
4+
description = "Rustc 开发指南"
5+
src = "src-zh"
56

67
[output.html]
78

‎src-zh/SUMMARY.md

+93
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,93 @@
1+
# Summary
2+
3+
[About this guide](./about-this-guide.md)
4+
5+
---
6+
7+
- [Part 1: Building, debugging, and contributing to Rustc](./part-1-intro.md)
8+
- [About the compiler team](./compiler-team.md)
9+
- [How to Build and Run the Compiler](./how-to-build-and-run.md)
10+
- [Build and Install distribution artifacts](./build-install-distribution-artifacts.md)
11+
- [Documenting Compiler](./compiler-documenting.md)
12+
- [The compiler testing framework](./tests/intro.md)
13+
- [Running tests](./tests/running.md)
14+
- [Adding new tests](./tests/adding.md)
15+
- [Using `compiletest` + commands to control test execution](./compiletest.md)
16+
- [Walkthrough: a typical contribution](./walkthrough.md)
17+
- [Implementing new features](./implementing_new_features.md)
18+
- [Stabilizing Features](./stabilization_guide.md)
19+
- [Debugging the Compiler](./compiler-debugging.md)
20+
- [Profiling the compiler](./profiling.md)
21+
- [with the linux perf tool](./profiling/with_perf.md)
22+
- [Coding conventions](./conventions.md)
23+
- [crates.io Dependencies](./crates-io.md)
24+
- [Emitting Errors and other Diagnostics](diagnostics.md)
25+
- [JSON diagnostic format](diagnostics/json-format.md)
26+
- [Part 2: How rustc works](./part-2-intro.md)
27+
- [High-level overview of the compiler source](./high-level-overview.md)
28+
- [The Rustc Driver and Interface](./rustc-driver.md)
29+
- [Rustdoc](./rustdoc.md)
30+
- [Queries: demand-driven compilation](./query.md)
31+
- [The Query Evaluation Model in Detail](./queries/query-evaluation-model-in-detail.md)
32+
- [Incremental compilation](./queries/incremental-compilation.md)
33+
- [Incremental compilation In Detail](./queries/incremental-compilation-in-detail.md)
34+
- [Debugging and Testing](./incrcomp-debugging.md)
35+
- [The parser](./the-parser.md)
36+
- [`#[test]` Implementation](./test-implementation.md)
37+
- [Macro expansion](./macro-expansion.md)
38+
- [Name resolution](./name-resolution.md)
39+
- [The HIR (High-level IR)](./hir.md)
40+
- [Lowering AST to HIR](./lowering.md)
41+
- [Debugging](./hir-debugging.md)
42+
- [The `ty` module: representing types](./ty.md)
43+
- [Kinds](./kinds.md)
44+
- [Type inference](./type-inference.md)
45+
- [Trait solving (old-style)](./traits/resolution.md)
46+
- [Higher-ranked trait bounds](./traits/hrtb.md)
47+
- [Caching subtleties](./traits/caching.md)
48+
- [Specialization](./traits/specialization.md)
49+
- [Trait solving (new-style)](./traits/index.md)
50+
- [Lowering to logic](./traits/lowering-to-logic.md)
51+
- [Goals and clauses](./traits/goals-and-clauses.md)
52+
- [Equality and associated types](./traits/associated-types.md)
53+
- [Implied bounds](./traits/implied-bounds.md)
54+
- [Region constraints](./traits/regions.md)
55+
- [The lowering module in rustc](./traits/lowering-module.md)
56+
- [Lowering rules](./traits/lowering-rules.md)
57+
- [Well-formedness checking](./traits/wf.md)
58+
- [Canonical queries](./traits/canonical-queries.md)
59+
- [Canonicalization](./traits/canonicalization.md)
60+
- [The SLG solver](./traits/slg.md)
61+
- [An Overview of Chalk](./traits/chalk-overview.md)
62+
- [Bibliography](./traits/bibliography.md)
63+
- [Type checking](./type-checking.md)
64+
- [Method Lookup](./method-lookup.md)
65+
- [Variance](./variance.md)
66+
- [Existential Types](./existential-types.md)
67+
- [The MIR (Mid-level IR)](./mir/index.md)
68+
- [MIR construction](./mir/construction.md)
69+
- [MIR visitor and traversal](./mir/visitor.md)
70+
- [MIR passes: getting the MIR for a function](./mir/passes.md)
71+
- [MIR optimizations](./mir/optimizations.md)
72+
- [Debugging](./mir/debugging.md)
73+
- [The borrow checker](./borrow_check.md)
74+
- [Tracking moves and initialization](./borrow_check/moves_and_initialization.md)
75+
- [Move paths](./borrow_check/moves_and_initialization/move_paths.md)
76+
- [MIR type checker](./borrow_check/type_check.md)
77+
- [Region inference](./borrow_check/region_inference.md)
78+
- [Two-phase-borrows](./borrow_check/two_phase_borrows.md)
79+
- [Constant evaluation](./const-eval.md)
80+
- [miri const evaluator](./miri.md)
81+
- [Parameter Environments](./param_env.md)
82+
- [Code Generation](./codegen.md)
83+
- [Updating LLVM](./codegen/updating-llvm.md)
84+
- [Debugging LLVM](./codegen/debugging.md)
85+
- [Profile-guided Optimization](./profile-guided-optimization.md)
86+
87+
---
88+
89+
[Appendix A: Stupid Stats](./appendix/stupid-stats.md)
90+
[Appendix B: Background material](./appendix/background.md)
91+
[Appendix C: Glossary](./appendix/glossary.md)
92+
[Appendix D: Code Index](./appendix/code-index.md)
93+
[](./important-links.md)

‎src-zh/about-this-guide.md

+31
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,31 @@
1+
# About this guide
2+
3+
This guide is meant to help document how rustc – the Rust compiler –
4+
works, as well as to help new contributors get involved in rustc
5+
development. It is not meant to replace code documentation – each
6+
chapter gives only high-level details – the kinds of things that
7+
(ideally) don't change frequently.
8+
9+
There are three parts to this guide. Part 1 contains information that should
10+
be useful no matter how you are contributing. Part 2 contains information
11+
about how the compiler works. Finally, there are some appendices at the
12+
end with useful reference information.
13+
14+
The guide itself is of course open-source as well, and the sources can
15+
be found at the [GitHub repository]. If you find any mistakes in the
16+
guide, please file an issue about it, or even better, open a PR
17+
with a correction!
18+
19+
## Other places to find information
20+
21+
You might also find the following sites useful:
22+
23+
- [Rustc API docs] -- rustdoc documentation for the compiler
24+
- [Forge] -- contains documentation about rust infrastructure, team procedures, and more
25+
- [compiler-team] -- the home-base for the rust compiler team, with description
26+
of the team procedures, active working groups, and the team calendar.
27+
28+
[GitHub repository]: https://github.com/rust-lang/rustc-guide/
29+
[Rustc API docs]: https://doc.rust-lang.org/nightly/nightly-rustc/rustc/
30+
[Forge]: https://forge.rust-lang.org/
31+
[compiler-team]: https://github.com/rust-lang/compiler-team/

‎src-zh/appendix/background.md

+128
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,128 @@
1+
# Appendix B: Background topics
2+
3+
This section covers a numbers of common compiler terms that arise in
4+
this guide. We try to give the general definition while providing some
5+
Rust-specific context.
6+
7+
<a name="cfg"></a>
8+
9+
## What is a control-flow graph?
10+
11+
A control-flow graph is a common term from compilers. If you've ever
12+
used a flow-chart, then the concept of a control-flow graph will be
13+
pretty familiar to you. It's a representation of your program that
14+
exposes the underlying control flow in a very clear way.
15+
16+
A control-flow graph is structured as a set of **basic blocks**
17+
connected by edges. The key idea of a basic block is that it is a set
18+
of statements that execute "together" – that is, whenever you branch
19+
to a basic block, you start at the first statement and then execute
20+
all the remainder. Only at the end of the block is there the
21+
possibility of branching to more than one place (in MIR, we call that
22+
final statement the **terminator**):
23+
24+
```mir
25+
bb0: {
26+
statement0;
27+
statement1;
28+
statement2;
29+
...
30+
terminator;
31+
}
32+
```
33+
34+
Many expressions that you are used to in Rust compile down to multiple
35+
basic blocks. For example, consider an if statement:
36+
37+
```rust,ignore
38+
a = 1;
39+
if some_variable {
40+
b = 1;
41+
} else {
42+
c = 1;
43+
}
44+
d = 1;
45+
```
46+
47+
This would compile into four basic blocks:
48+
49+
```mir
50+
BB0: {
51+
a = 1;
52+
if some_variable { goto BB1 } else { goto BB2 }
53+
}
54+
55+
BB1: {
56+
b = 1;
57+
goto BB3;
58+
}
59+
60+
BB2: {
61+
c = 1;
62+
goto BB3;
63+
}
64+
65+
BB3: {
66+
d = 1;
67+
...;
68+
}
69+
```
70+
71+
When using a control-flow graph, a loop simply appears as a cycle in
72+
the graph, and the `break` keyword translates into a path out of that
73+
cycle.
74+
75+
<a name="dataflow"></a>
76+
77+
## What is a dataflow analysis?
78+
79+
[*Static Program Analysis*](https://cs.au.dk/~amoeller/spa/) by Anders Møller
80+
and Michael I. Schwartzbach is an incredible resource!
81+
82+
*to be written*
83+
84+
<a name="quantified"></a>
85+
86+
## What is "universally quantified"? What about "existentially quantified"?
87+
88+
*to be written*
89+
90+
<a name="variance"></a>
91+
92+
## What is co- and contra-variance?
93+
94+
Check out the subtyping chapter from the
95+
[Rust Nomicon](https://doc.rust-lang.org/nomicon/subtyping.html).
96+
97+
See the [variance](../variance.html) chapter of this guide for more info on how
98+
the type checker handles variance.
99+
100+
<a name="free-vs-bound"></a>
101+
102+
## What is a "free region" or a "free variable"? What about "bound region"?
103+
104+
Let's describe the concepts of free vs bound in terms of program
105+
variables, since that's the thing we're most familiar with.
106+
107+
- Consider this expression, which creates a closure: `|a,
108+
b| a + b`. Here, the `a` and `b` in `a + b` refer to the arguments
109+
that the closure will be given when it is called. We say that the
110+
`a` and `b` there are **bound** to the closure, and that the closure
111+
signature `|a, b|` is a **binder** for the names `a` and `b`
112+
(because any references to `a` or `b` within refer to the variables
113+
that it introduces).
114+
- Consider this expression: `a + b`. In this expression, `a` and `b`
115+
refer to local variables that are defined *outside* of the
116+
expression. We say that those variables **appear free** in the
117+
expression (i.e., they are **free**, not **bound** (tied up)).
118+
119+
So there you have it: a variable "appears free" in some
120+
expression/statement/whatever if it refers to something defined
121+
outside of that expressions/statement/whatever. Equivalently, we can
122+
then refer to the "free variables" of an expression – which is just
123+
the set of variables that "appear free".
124+
125+
So what does this have to do with regions? Well, we can apply the
126+
analogous concept to type and regions. For example, in the type `&'a
127+
u32`, `'a` appears free. But in the type `for<'a> fn(&'a u32)`, it
128+
does not.

‎src-zh/appendix/code-index.md

+46
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,46 @@
1+
# Appendix D: Code Index
2+
3+
rustc has a lot of important data structures. This is an attempt to give some
4+
guidance on where to learn more about some of the key data structures of the
5+
compiler.
6+
7+
Item | Kind | Short description | Chapter | Declaration
8+
----------------|----------|-----------------------------|--------------------|-------------------
9+
`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+
`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)
11+
`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)
12+
`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)
13+
`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)
14+
`DiagnosticBuilder` | struct | A struct for building up compiler diagnostics, such as errors or lints | [Emitting Diagnostics] | [src/librustc_errors/diagnostic_builder.rs](https://doc.rust-lang.org/nightly/nightly-rustc/rustc_errors/struct.DiagnosticBuilder.html)
15+
`DocContext` | struct | A state container used by rustdoc when crawling through a crate to gather its documentation | [Rustdoc] | [src/librustdoc/core.rs](https://github.com/rust-lang/rust/blob/master/src/librustdoc/core.rs)
16+
`HirId` | 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.HirId.html)
17+
`NodeId` | struct | One of four types of HIR node identifiers. Being phased out | [Identifiers in the HIR] | [src/libsyntax/ast.rs](https://doc.rust-lang.org/nightly/nightly-rustc/syntax/ast/struct.NodeId.html)
18+
`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)
19+
`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)
20+
`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)
22+
`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)
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)
24+
`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)
25+
`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)
26+
`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)
27+
`StringReader` | struct | This is the lexer used during parsing. It consumes characters from the raw source code being compiled and produces a series of tokens for use by the rest of the parser | [The parser] | [src/libsyntax/parse/lexer/mod.rs](https://doc.rust-lang.org/nightly/nightly-rustc/syntax/parse/lexer/struct.StringReader.html)
28+
`syntax::token_stream::TokenStream` | struct | An abstract sequence of tokens, organized into `TokenTree`s | [The parser], [Macro expansion] | [src/libsyntax/tokenstream.rs](https://doc.rust-lang.org/nightly/nightly-rustc/syntax/tokenstream/struct.TokenStream.html)
29+
`TraitDef` | struct | This struct contains a trait's definition with type information | [The `ty` modules] | [src/librustc/ty/trait_def.rs](https://doc.rust-lang.org/nightly/nightly-rustc/rustc/ty/trait_def/struct.TraitDef.html)
30+
`TraitRef` | struct | The combination of a trait and its input types (e.g. `P0: Trait<P1...Pn>`) | [Trait Solving: Goals and Clauses], [Trait Solving: Lowering impls] | [src/librustc/ty/sty.rs](https://doc.rust-lang.org/nightly/nightly-rustc/rustc/ty/struct.TraitRef.html)
31+
`Ty<'tcx>` | struct | This is the internal representation of a type used for type checking | [Type checking] | [src/librustc/ty/mod.rs](https://doc.rust-lang.org/nightly/nightly-rustc/rustc/ty/type.Ty.html)
32+
`TyCtxt<'cx, 'tcx, 'tcx>` | struct | The "typing context". This is the central data structure in the compiler. It is the context that you use to perform all manner of queries | [The `ty` modules] | [src/librustc/ty/context.rs](https://doc.rust-lang.org/nightly/nightly-rustc/rustc/ty/struct.TyCtxt.html)
33+
34+
[The HIR]: ../hir.html
35+
[Identifiers in the HIR]: ../hir.html#hir-id
36+
[The parser]: ../the-parser.html
37+
[The Rustc Driver and Interface]: ../rustc-driver.html
38+
[Type checking]: ../type-checking.html
39+
[The `ty` modules]: ../ty.html
40+
[Rustdoc]: ../rustdoc.html
41+
[Emitting Diagnostics]: ../diagnostics.html
42+
[Macro expansion]: ../macro-expansion.html
43+
[Name resolution]: ../name-resolution.html
44+
[Parameter Environment]: ../param_env.html
45+
[Trait Solving: Goals and Clauses]: ../traits/goals-and-clauses.html#domain-goals
46+
[Trait Solving: Lowering impls]: ../traits/lowering-rules.html#lowering-impls

0 commit comments

Comments
 (0)