]>
Commit | Line | Data |
---|---|---|
8bb4bdeb XL |
1 | # Introduction |
2 | ||
6a06907d XL |
3 | This book is the primary reference for the Rust programming language. |
4 | It provides three kinds of material: | |
8bb4bdeb XL |
5 | |
6 | - Chapters that informally describe each language construct and their use. | |
6a06907d XL |
7 | - Chapters that informally describe the memory model, concurrency model, runtime services, linkage model, and debugging facilities. |
8 | - Appendix chapters providing rationale and references to languages that influenced the design. | |
8bb4bdeb | 9 | |
b7449926 XL |
10 | <div class="warning"> |
11 | ||
6a06907d XL |
12 | Warning: |
13 | This book is incomplete. Documenting everything takes a while. | |
14 | See the [GitHub issues] for what is not documented in this book. | |
b7449926 XL |
15 | |
16 | </div> | |
17 | ||
6a06907d | 18 | ## Rust releases |
b7449926 | 19 | |
6a06907d XL |
20 | Rust has a new language release every six weeks. |
21 | The first stable release of the language was Rust 1.0.0, followed by Rust 1.1.0 and so on. | |
22 | Tools (`rustc`, `cargo`, etc.) and documentation ([Standard library], this book, etc.) are released with the language release. | |
8bb4bdeb | 23 | |
6a06907d XL |
24 | The latest release of this book, matching the latest Rust version, can always be found at <https://doc.rust-lang.org/reference/>. |
25 | Prior versions can be found by adding the Rust version before the "reference" directory. | |
26 | For example, the Reference for Rust 1.49.0 is located at <https://doc.rust-lang.org/1.49.0/reference/>. | |
8bb4bdeb | 27 | |
6a06907d | 28 | ## What *The Reference* is not |
b7449926 | 29 | |
6a06907d XL |
30 | This book does not serve as an introduction to the language. |
31 | Background familiarity with the language is assumed. | |
32 | A separate [book] is available to help acquire such background familiarity. | |
abe05a73 | 33 | |
6a06907d XL |
34 | This book also does not serve as a reference to the [standard library] included in the language distribution. |
35 | Those libraries are documented separately by extracting documentation attributes from their source code. | |
36 | Many of the features that one might expect to be language features are library features in Rust, so what you're looking for may be there, not here. | |
fc512014 | 37 | |
6a06907d XL |
38 | Similarly, this book does not usually document the specifics of `rustc` as a tool or of Cargo. |
39 | `rustc` has its own [book][rustc book]. | |
40 | Cargo has a [book][cargo book] that contains a [reference][cargo reference]. | |
41 | There are a few pages such as [linkage] that still describe how `rustc` works. | |
b7449926 | 42 | |
6a06907d XL |
43 | This book also only serves as a reference to what is available in stable Rust. |
44 | For unstable features being worked on, see the [Unstable Book]. | |
b7449926 | 45 | |
6a06907d XL |
46 | Rust compilers, including `rustc`, will perform optimizations. |
47 | The reference does not specify what optimizations are allowed or disallowed. | |
48 | Instead, think of the compiled program as a black box. | |
49 | You can only probe by running it, feeding it input and observing its output. | |
50 | Everything that happens that way must conform to what the reference says. | |
51 | ||
52 | Finally, this book is not normative. | |
53 | It may include details that are specific to `rustc` itself, and should not be taken as a specification for the Rust language. | |
54 | We intend to produce such a book someday, and until then, the reference is the closest thing we have to one. | |
55 | ||
56 | ## How to use this book | |
57 | ||
58 | This book does not assume you are reading this book sequentially. | |
59 | Each chapter generally can be read standalone, but will cross-link to other chapters for facets of the language they refer to, but do not discuss. | |
b7449926 XL |
60 | |
61 | There are two main ways to read this document. | |
62 | ||
6a06907d XL |
63 | The first is to answer a specific question. |
64 | If you know which chapter answers that question, you can jump to that chapter in the table of contents. | |
cdc7bbd5 | 65 | Otherwise, you can press `s` or click the magnifying glass on the top bar to search for keywords related to your question. |
6a06907d XL |
66 | For example, say you wanted to know when a temporary value created in a let statement is dropped. |
67 | If you didn't already know that the [lifetime of temporaries] is defined in the [expressions chapter], you could search "temporary let" and the first search result will take you to that section. | |
b7449926 XL |
68 | |
69 | The second is to generally improve your knowledge of a facet of the language. | |
6a06907d XL |
70 | In that case, just browse the table of contents until you see something you want to know more about, and just start reading. |
71 | If a link looks interesting, click it, and read about that section. | |
b7449926 | 72 | |
6a06907d | 73 | That said, there is no wrong way to read this book. Read it however you feel helps you best. |
b7449926 XL |
74 | |
75 | ### Conventions | |
76 | ||
6a06907d XL |
77 | Like all technical books, this book has certain conventions in how it displays information. |
78 | These conventions are documented here. | |
b7449926 | 79 | |
6a06907d XL |
80 | * Statements that define a term contain that term in *italics*. |
81 | Whenever that term is used outside of that chapter, it is usually a link to the section that has this definition. | |
b7449926 | 82 | |
0bf4aa26 XL |
83 | An *example term* is an example of a term being defined. |
84 | ||
6a06907d | 85 | * Differences in the language by which edition the crate is compiled under are in a blockquote that start with the words "Edition Differences:" in **bold**. |
0bf4aa26 | 86 | |
6a06907d | 87 | > **Edition Differences**: In the 2015 edition, this syntax is valid that is disallowed as of the 2018 edition. |
b7449926 | 88 | |
6a06907d | 89 | * Notes that contain useful information about the state of the book or point out useful, but mostly out of scope, information are in blockquotes that start with the word "Note:" in **bold**. |
b7449926 XL |
90 | |
91 | > **Note**: This is an example note. | |
92 | ||
6a06907d | 93 | * Warnings that show unsound behavior in the language or possibly confusing interactions of language features are in a special warning box. |
b7449926 XL |
94 | |
95 | <div class="warning"> | |
96 | ||
97 | Warning: This is an example warning. | |
98 | ||
99 | </div> | |
100 | ||
101 | * Code snippets inline in the text are inside `<code>` tags. | |
102 | ||
6a06907d | 103 | Longer code examples are in a syntax highlighted box that has controls for copying, executing, and showing hidden lines in the top right corner. |
b7449926 XL |
104 | |
105 | ```rust | |
106 | # // This is a hidden line. | |
107 | fn main() { | |
108 | println!("This is a code example"); | |
109 | } | |
110 | ``` | |
111 | ||
6a06907d | 112 | * The grammar and lexical structure is in blockquotes with either "Lexer" or "Syntax" in <sup>**bold superscript**</sup> as the first line. |
b7449926 XL |
113 | |
114 | > **<sup>Syntax</sup>**\ | |
115 | > _ExampleGrammar_:\ | |
116 | > `~` [_Expression_]\ | |
117 | > | `box` [_Expression_] | |
8bb4bdeb | 118 | |
9fa01778 XL |
119 | See [Notation] for more detail. |
120 | ||
b7449926 | 121 | ## Contributing |
8bb4bdeb | 122 | |
b7449926 | 123 | We welcome contributions of all kinds. |
ea8adc8c | 124 | |
6a06907d XL |
125 | You can contribute to this book by opening an issue or sending a pull request to [the Rust Reference repository]. |
126 | If this book does not answer your question, and you think its answer is in scope of it, please do not hesitate to [file an issue] or ask about it in the `t-lang/doc` stream on [Zulip]. | |
127 | Knowing what people use this book for the most helps direct our attention to making those sections the best that they can be. | |
128 | We also want the reference to be as normative as possible, so if you see anything that is wrong or is non-normative but not specifically called out, please also [file an issue]. | |
cc61c64b | 129 | |
8bb4bdeb | 130 | [book]: ../book/index.html |
60c5eb7d | 131 | [github issues]: https://github.com/rust-lang/reference/issues |
b7449926 | 132 | [standard library]: ../std/index.html |
60c5eb7d | 133 | [the Rust Reference repository]: https://github.com/rust-lang/reference/ |
b7449926 | 134 | [Unstable Book]: https://doc.rust-lang.org/nightly/unstable-book/ |
416331ca | 135 | [_Expression_]: expressions.md |
b7449926 XL |
136 | [cargo book]: ../cargo/index.html |
137 | [cargo reference]: ../cargo/reference/index.html | |
f9f354fc | 138 | [expressions chapter]: expressions.html |
fc512014 | 139 | [file an issue]: https://github.com/rust-lang/reference/issues |
f9f354fc XL |
140 | [lifetime of temporaries]: expressions.html#temporaries |
141 | [linkage]: linkage.html | |
b7449926 | 142 | [rustc book]: ../rustc/index.html |
416331ca | 143 | [Notation]: notation.md |
fc512014 | 144 | [Zulip]: https://rust-lang.zulipchat.com/#narrow/stream/237824-t-lang.2Fdoc |