2017-02-15 19:57:33 +00:00
|
|
|
# Introduction
|
|
|
|
|
2018-08-24 05:16:45 +00:00
|
|
|
This book is the primary reference for the Rust programming language. It
|
2017-02-15 19:57:33 +00:00
|
|
|
provides three kinds of material:
|
|
|
|
|
|
|
|
- Chapters that informally describe each language construct and their use.
|
|
|
|
- Chapters that informally describe the memory model, concurrency model,
|
|
|
|
runtime services, linkage model and debugging facilities.
|
|
|
|
- Appendix chapters providing rationale and references to languages that
|
|
|
|
influenced the design.
|
|
|
|
|
2018-08-24 05:07:16 +00:00
|
|
|
> **Note**: You may also be interested in the [grammar].
|
2018-08-24 04:13:46 +00:00
|
|
|
|
|
|
|
<div class="warning">
|
|
|
|
|
2018-08-24 05:16:45 +00:00
|
|
|
Warning: This book is incomplete. Documenting everything takes a
|
2018-08-24 04:13:46 +00:00
|
|
|
while. We have a [big issue] to track documentation for every Rust feature,
|
|
|
|
so check that out if you can't find something here.
|
|
|
|
|
|
|
|
</div>
|
|
|
|
|
|
|
|
## What *The Reference* is Not
|
|
|
|
|
2018-08-24 05:16:45 +00:00
|
|
|
This book does not serve as an introduction to the language. Background
|
2017-02-15 19:57:33 +00:00
|
|
|
familiarity with the language is assumed. A separate [book] is available to
|
|
|
|
help acquire such background familiarity.
|
|
|
|
|
2018-08-24 05:16:45 +00:00
|
|
|
This book also does not serve as a reference to the [standard library]
|
2017-02-15 19:57:33 +00:00
|
|
|
included in the language distribution. Those libraries are documented
|
|
|
|
separately by extracting documentation attributes from their source code. 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.
|
|
|
|
|
2018-08-24 05:16:45 +00:00
|
|
|
Similarly, this book does not usually book the specifics of `rustc` as a
|
2018-08-25 08:07:54 +00:00
|
|
|
tool or of Cargo. `rustc` has its own [book][rustc book]. Cargo has a
|
|
|
|
[book][cargo book] that contains a [reference][cargo reference]. There are a few
|
|
|
|
pages such as [linkage] that still describe how `rustc` works.
|
2018-08-24 04:10:11 +00:00
|
|
|
|
2018-08-24 05:16:45 +00:00
|
|
|
This book also only serves as a reference to what is available in stable
|
2018-08-24 04:10:11 +00:00
|
|
|
Rust. For unstable features being worked on, see the [Unstable Book].
|
2017-10-12 05:21:15 +00:00
|
|
|
|
2018-08-24 05:16:45 +00:00
|
|
|
Finally, this book is not normative. It may include details that are
|
2017-02-15 19:57:33 +00:00
|
|
|
specific to `rustc` itself, and should not be taken as a specification for
|
2018-08-24 05:16:45 +00:00
|
|
|
the Rust language. We intend to produce such a book someday, and until then,
|
2018-08-24 04:10:11 +00:00
|
|
|
the reference is the closest thing we have to one.
|
|
|
|
|
2018-08-24 05:07:16 +00:00
|
|
|
## How to Use This Book
|
2018-08-24 04:13:46 +00:00
|
|
|
|
2018-08-24 05:16:45 +00:00
|
|
|
This book does not assume you are reading this book sequentially. Each
|
2018-08-24 05:07:16 +00:00
|
|
|
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.
|
|
|
|
|
|
|
|
There are two main ways to read this document.
|
|
|
|
|
|
|
|
The first is to answer a specific question. If you know which chapter answers
|
|
|
|
that question, you can jump to that chapter in the table of contents. Otherwise,
|
|
|
|
you can press `s` or the click the magnifying glass on the top bar to search for
|
|
|
|
keywords related to your question. For example, say you wanted to know when a
|
|
|
|
temporary value created in a let statement is dropped. 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.
|
|
|
|
|
|
|
|
The second is to generally improve your knowledge of a facet of the language.
|
|
|
|
In that case, just browse the table of contents until you see something you
|
|
|
|
want to know more about, and just start reading. If a link looks interesting,
|
|
|
|
click it, and read about that section.
|
|
|
|
|
|
|
|
That said, there is no wrong way to read this book. Read it however you feel
|
|
|
|
helps you best.
|
|
|
|
|
|
|
|
### Conventions
|
|
|
|
|
|
|
|
Like all technical books, this book has certain conventions in how it displays
|
|
|
|
information. These conventions are documented here.
|
|
|
|
|
|
|
|
* Statements that define a term contain that term in *italics*. Whenever that
|
|
|
|
term is used outside of that chapter, it is usually a link to the section that
|
|
|
|
has this definition.
|
|
|
|
|
|
|
|
An *example term* is an example of a term beind defined.
|
|
|
|
|
|
|
|
* 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**.
|
|
|
|
|
|
|
|
> Note: This is an example note.
|
|
|
|
|
|
|
|
* Warnings that show unsound behavior in the language or possibly confusing
|
|
|
|
interactions of language features are in a special warning box.
|
|
|
|
|
|
|
|
<div class="warning">
|
|
|
|
|
|
|
|
Warning: This is an example warning.
|
|
|
|
|
|
|
|
</div>
|
|
|
|
|
|
|
|
* Code snippets inline in the text are inside `<code>` tags.
|
|
|
|
|
|
|
|
Longer code examples are in a syntax highlighted box that has controls for
|
|
|
|
copying, executing, and showing hidden lines in the top right corner.
|
|
|
|
|
|
|
|
```rust
|
|
|
|
# // This is a hidden line.
|
|
|
|
fn main() {
|
|
|
|
println!("This is a code example");
|
|
|
|
}
|
|
|
|
```
|
|
|
|
|
|
|
|
* The grammar and lexical structure is in blockquotes with either "Lexer" or
|
|
|
|
"Syntax" in **bold** as the first line in <sup>superscript</sup>.
|
|
|
|
|
|
|
|
> **<sup>Syntax</sup>**\
|
|
|
|
> _ExampleGrammar_:\
|
|
|
|
> `~` [_Expression_]\
|
|
|
|
> | `box` [_Expression_]
|
2017-02-15 19:57:33 +00:00
|
|
|
|
2018-08-24 04:13:46 +00:00
|
|
|
## Contributing
|
|
|
|
|
2018-08-25 08:07:54 +00:00
|
|
|
We welcome contributions of all kinds.
|
2017-02-15 19:57:33 +00:00
|
|
|
|
2018-08-24 05:16:45 +00:00
|
|
|
You can contribute to this book by opening an issue or sending a pull
|
|
|
|
request to [the Rust Reference repository]. If this book does not answer
|
2018-08-24 04:10:11 +00:00
|
|
|
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 Rust docs channels on IRC or
|
2018-08-24 05:16:45 +00:00
|
|
|
discord. Knowing what people use this book for the most helps direct our
|
2018-08-24 04:10:11 +00:00
|
|
|
attention to making those sections the best that they can be.
|
2017-09-06 18:20:16 +00:00
|
|
|
|
2017-02-21 04:08:55 +00:00
|
|
|
[book]: ../book/index.html
|
2018-08-24 04:10:11 +00:00
|
|
|
[standard library]: ../std/index.html
|
2017-02-21 04:08:55 +00:00
|
|
|
[grammar]: ../grammar.html
|
2017-09-06 18:20:16 +00:00
|
|
|
[the Rust Reference repository]: https://github.com/rust-lang-nursery/reference/
|
2017-03-31 13:51:29 +00:00
|
|
|
[big issue]: https://github.com/rust-lang-nursery/reference/issues/9
|
2018-08-24 04:10:11 +00:00
|
|
|
[Unstable Book]: https://doc.rust-lang.org/nightly/unstable-book/
|
2018-08-24 05:07:16 +00:00
|
|
|
[_Expression_]: expressions.html
|
2018-08-24 04:10:11 +00:00
|
|
|
[cargo book]: ../cargo/index.html
|
|
|
|
[cargo reference]: ../cargo/reference/index.html
|
2018-08-24 05:07:16 +00:00
|
|
|
[expressions chapter]: expressions.html
|
|
|
|
[lifetime of temporaries]: expressions.html#temporary-lifetimes
|
2018-08-25 08:07:54 +00:00
|
|
|
[linkage]: linkage.html
|
|
|
|
[rustc book]: ../rustc/index.html
|