## File: README.md

# The Rust Programming Language



This repository contains the source of "The Rust Programming Language" book.

[The book is available in dead-tree form from No Starch Press][nostarch].

[nostarch]: https://nostarch.com/rust-programming-language-2nd-edition

You can also read the book for free online. Please see the book as shipped with
the latest [stable], [beta], or [nightly] Rust releases. Be aware that issues
in those versions may have been fixed in this repository already, as those
releases are updated less frequently.

[stable]: https://doc.rust-lang.org/stable/book/
[beta]: https://doc.rust-lang.org/beta/book/
[nightly]: https://doc.rust-lang.org/nightly/book/

See the [releases] to download just the code of all the code listings that appear in the book.

[releases]: https://github.com/rust-lang/book/releases

## Requirements

Building the book requires [mdBook], ideally the same version that
rust-lang/rust uses in [this file][rust-mdbook]. To get it:

[mdBook]: https://github.com/rust-lang/mdBook
[rust-mdbook]: https://github.com/rust-lang/rust/blob/HEAD/src/tools/rustbook/Cargo.toml

```bash
$ cargo install mdbook --locked --version <version_num>
```

## Building

To build the book, type:

```bash
$ mdbook build
```

The output will be in the `book` subdirectory. To check it out, open it in
your web browser.

_Firefox:_

```bash
$ firefox book/index.html                       # Linux
$ open -a "Firefox" book/index.html             # OS X
$ Start-Process "firefox.exe" .\book\index.html # Windows (PowerShell)
$ start firefox.exe .\book\index.html           # Windows (Cmd)
```

_Chrome:_

```bash
$ google-chrome book/index.html                 # Linux
$ open -a "Google Chrome" book/index.html       # OS X
$ Start-Process "chrome.exe" .\book\index.html  # Windows (PowerShell)
$ start chrome.exe .\book\index.html            # Windows (Cmd)
```

To run the tests:

```bash
$ cd packages/trpl
$ mdbook test --library-path packages/trpl/target/debug/deps
```

## Contributing

We'd love your help! Please see [CONTRIBUTING.md][contrib] to learn about the
kinds of contributions we're looking for.

[contrib]: https://github.com/rust-lang/book/blob/main/CONTRIBUTING.md

Because the book is [printed][nostarch], and because we want
to keep the online version of the book close to the print version when
possible, it may take longer than you're used to for us to address your issue
or pull request.

So far, we've been doing a larger revision to coincide with [Rust Editions](https://doc.rust-lang.org/edition-guide/). Between those larger
revisions, we will only be correcting errors. If your issue or pull request
isn't strictly fixing an error, it might sit until the next time that we're
working on a large revision: expect on the order of months or years. Thank you
for your patience!

### Translations

We'd love help translating the book! See the [Translations] label to join in
efforts that are currently in progress. Open a new issue to start working on
a new language! We're waiting on [mdbook support] for multiple languages
before we merge any in, but feel free to start!

[Translations]: https://github.com/rust-lang/book/issues?q=is%3Aopen+is%3Aissue+label%3ATranslations
[mdbook support]: https://github.com/rust-lang/mdBook/issues/5

## Spellchecking

To scan source files for spelling errors, you can use the `spellcheck.sh`
script available in the `ci` directory. It needs a dictionary of valid words,
which is provided in `ci/dictionary.txt`. If the script produces a false
positive (say, you used the word `BTreeMap` which the script considers invalid),
you need to add this word to `ci/dictionary.txt` (keep the sorted order for
consistency).

---

## File: first-edition/src/README.md

# The Rust Programming Language

The first edition of the book is no longer distributed with Rust's documentation.

If you came here via a link or web search, you may want to check out [the current
version of the book](../index.html) instead.

If you have an internet connection, you can [find a copy distributed with
Rust
1.30](https://doc.rust-lang.org/1.30.0/book/first-edition/README.html).

---

## File: packages/trpl/README.md

# The Rust Programming Language Book Crate



This repository is the home of the `trpl` crate used in _The Rust Programming
Language_ book materials.

This crate mostly just re-exports items from _other_ crates. It exists for two
main reasons:

1. So that as you read along in _The Rust Programming Language_, you can add
   just one dependency, rather than however many we end up with, and likewise
   use only one set of imports.

2. So that we can more easily guarantee it keeps building and working. Since we
   control the contents of this crate and when it changes, readers will never be
   broken by upstream changes, e.g. if Tokio does a breaking 2.0 release at some
   point.

## Requirements

This crate currently requires at least Rust 1.79.

---

## File: packages/mdbook-trpl/src/bin/README - mdbook-trpl-note.md

# mdbook-trpl-note

This is a _very_ simple [preprocessor][pre] for [mdBook][mdbook], focused specifically on the content of _The Rust Programming Language_ book. This preprocessor takes Markdown like this—

```markdown
> Note: This is some material we want to provide more emphasis for, because it
> is important in some way!

Some text.

> ## Some subject
>
> Here is all the important things to know about that particular subject.
```

—and rewrites the Markdown to this:

```html
<section class="note" aria-role="note">

This is some material we want to provide more emphasis for, because it is
important in some way!

</section>

Some text.

<section class="note" aria-role="note">

## Some subject

Here is all the important things to know about that particular subject.

</section>
```

This allows using the relatively standard Markdown convention of (incorrectly!) using blockquotes for “callouts” or “notes” like this, while still producing semantic HTML which conveys the actual intent.

> [!NOTE]
> This is _not_ a full “admonition” preprocessor, and it is not remotely compliant with [the GitHub “alert” syntax][alerts]. It exists almost entirely for the sake of providing better semantic HTML for _The Rust Programming Language_ book with a minimum of disruption to existing workflows!
>
> You are probably better off using one of the other existing alert/admonition preprocessors:
>
> - [mdbook-alerts][mdbook-alerts]
> - [mdbook-admonish][mdbook-admonish]

[pre]: https://rust-lang.github.io/mdBook/format/configuration/preprocessors.html
[mdbook]: https://github.com/rust-lang/mdBook
[alerts]: https://docs.github.com/en/get-started/writing-on-github/getting-started-with-writing-and-formatting-on-github/basic-writing-and-formatting-syntax#alerts
[mdbook-alerts]: https://github.com/lambdalisue/rs-mdbook-alerts
[mdbook-admonish]: https://github.com/tommilligan/mdbook-admonish

---

## File: packages/mdbook-trpl/README.md

# mdbook_trpl

A shared package for [mdbook][mdbook] [preprocessors][pre] used in [_The Rust
Programming Language_][trpl].

Supplies the following preprocessor binaries:

- [mdbook-trpl-note](./src/bin/note)
- [mdbook-trpl-listing](./src/bin/listing)

[mdbook]: https://crates.io/crates/mdbook
[pre]: https://rust-lang.github.io/mdBook/format/configuration/preprocessors.html
[trpl]: https://doc.rust-lang.org/book/

---

## File: redirects/README.md

% The Rust Programming Language

There are two editions of "The Rust Programming Language":

* [First edition](first-edition/index.html)
* [Second edition](second-edition/index.html)

The second edition is a complete re-write. It is still under construction;
though it is far enough along to learn most of Rust; we suggest reading the
second edition and then checking out the first edition later to pick up some of
the more esoteric parts of the language.