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