rust-lang / book

The Rust Programming Language

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.

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.

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

Requirements

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

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

Building

To build the book, type:

$ mdbook build

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

Firefox:

$ 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:

$ 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:

$ mdbook test

Contributing

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

Because the book is printed, 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. 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!

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).

book's Issues

Discussion on section 5: Basic Data Types

Discussion on section 9: Basic Collections

Explain alarmed ferris convention in chapter 1 for code that doesn't compile on purpose

This example from Learn Rust doesn't work -

extern crate rand;

use std::io;
use std::cmp::Ordering;
use rand::Rng;

fn main() {
    println!("Guess the number!");

    let secret_number = rand::thread_rng().gen_range(1, 101);

    println!("The secret number is: {}", secret_number);

    println!("Please input your guess.");

    let mut guess = String::new();

    io::stdin().read_line(&mut guess)
        .ok()
        .expect("failed to read line");

    println!("You guessed: {}", guess);

    match guess.cmp(&secret_number) {
        Ordering::Less    => println!("Too small!"),
        Ordering::Greater => println!("Too big!"),
        Ordering::Equal   => println!("You win!"),
    }
}

I am using Rust 1.5 on OSX and the example doesn't work on Rust playground either.

Discussion on section 23: Nightly Rust

Impossible to click on scroll bar

When on http://rust-lang.github.io/book/ , it is impossible to click on the scroll bar on the right edge of the screen (maximized window) because the large right-arrow link to http://rust-lang.github.io/book/installation.html covers it. Frankly I'm not even sure how that's possible, but there it is.

Firefox 44.

'Cargo install mdbook' throws error E0365

I am completely new to both programming and RUST.

I tried the given command, cargo install mdbook and I ended up with the following error output.

/home/suranand/.cargo/registry/src/github.com-88ac128001ac3a9a/notify-2.4.1/src/lib.rs:7:9: 7:21 error: `Op` is private, and cannot be reexported [E0365]
/home/suranand/.cargo/registry/src/github.com-88ac128001ac3a9a/notify-2.4.1/src/lib.rs:7 pub use self::op::Op;
                                                                                                 ^~~~~~~~~~~~
/home/suranand/.cargo/registry/src/github.com-88ac128001ac3a9a/notify-2.4.1/src/lib.rs:7:9: 7:21 help: run `rustc --explain E0365` to see a detailed explanation
/home/suranand/.cargo/registry/src/github.com-88ac128001ac3a9a/notify-2.4.1/src/lib.rs:7:9: 7:21 note: Consider declaring module `Op` as a `pub mod`
/home/suranand/.cargo/registry/src/github.com-88ac128001ac3a9a/notify-2.4.1/src/lib.rs:7 pub use self::op::Op;
                                                                                                 ^~~~~~~~~~~~
error: aborting due to previous error
Build failed, waiting for other jobs to finish...
failed to compile `mdbook v0.0.9`, intermediate artifacts can be found at `/media/wind/A-Life/2016/rust/rustdocs/target-install`

Caused by:
  Could not compile `notify`.

To learn more, run the command again with --verbose.

Discussion on section 18: FFI

Discussion on Section 13: I/O

Discussion on section 15: Smart Pointers

Discussion on section 4: Ownership and borrowing

Small typo on intro page.

There Is a small typo on the intro page to the book. Will attack a screenshot. 'auseful' should be changed to 'a useful'.

Discussion on section 19: Cargo

Borrowing: durations and lifetimes

From @aturon in #59

I think we will want to add material on:

• The notion that borrows have a "duration" (i.e. a lifetime, but we can avoid the syntax)
• The fact that, for the duration of a borrow, the original object is inaccessible. But after the borrow expires, you can access it again.

My thoughts:

I thought this was sorta implied by the 'dangling' section, but maybe it could be its own section too? Or dangling would be a sub-section of it?

Consider adding a dedicated boxing section in effective rust

I tried to learn rust early on and boxing seemed to be a much bigger thing than it is now. The book frequently makes references to boxing, as for example in the closures section. There are references to boxes scattered throughout and the only page that has box in the title is a quick bit on Box Syntax and Patterns in the nightly section. Boxing seems to still be pretty important. The text mostly assumes knowledge on what boxing is or how to use it. I would have found it helpful to have a dedicated page on boxing for what it's worth.

I really have found the documentation useful and helpful and thank you so much for writing it! I am creating issues but I mostly think the documentation is excellent.

Disucssion on Section 2: Tutorial

References: non-idiomatic code

The function calculate_length in the 2nd code example isn't very idiomatic; but this might be to reduce noise in the transition from the tuple- returning function to the usize returning function. (let length = x; length is better written as x)

• @Mark-Simulacrum

Explain the `ref` keyword in the "References" section

This page on references should discuss and make use of ref in an example. I ran into ref on Patterns, which links back to the references page, but it never uses it. I also ran into ref when looking at Some and I actually went to the references page then trying to look for information about ref and did not find it.

Discussion on section 6: Enums

Discussion on section 1: Introduction

Borrowing: provide more motivation

From @aturon in #59

For mutable references, you mention the rule restricting aliasing, but you don't provide a motivation. I think it's really good to try to include an example of how aliasing + mutation gets you into trouble. Happy to help brainstorm here.

mention `--nocapture` in the Testing chapter?

I'm new to Rust, and having just finished making my tests pass, I added a few println!() to the test case to dump more information about some function's return value. I then proceeded to tear my hair out for a few hours because suddenly all my debug prints were being ignored. I eventually discovered a stackoverflow post which clued me into running cargo test -- --nocapture to allow println messages from passing tests to be displayed.

I'd love it if the chapter on Testing found a way to drop this tidbit into the flow somewhere. It's not exactly a "testing" tool, per se, but since tests are where a lot of beginners are going to do their experiments, and since the venerable printf is such a common experimental tool, it'd be nice if this hide-stdout property got mentioned somewhere a beginner might notice it. Maybe even a pointer to whereever it is (I haven't found it myself, yet) that lists the valid arguments that accepted by the test programs created by cargo test.

thanks!

Guessing Game: error: mismatched types

The Comparing guesses example does not compile:

   Compiling rust-playground v0.1.0 (file:///home/filip/Documents/Projects/rust-playground)
src/main.rs:23:21: 23:35 error: mismatched types:
 expected `&collections::string::String`,
    found `&_`
(expected struct `collections::string::String`,
    found integral variable) [E0308]
src/main.rs:23     match guess.cmp(&secret_number) {
                                   ^~~~~~~~~~~~~~
src/main.rs:23:21: 23:35 help: run `rustc --explain E0308` to see a detailed explanation
error: aborting due to previous error
Could not compile `rust-playground`.

To learn more, run the command again with --verbose.

I'm running Arch Linux with rust 1.7.0.

Broken links in Nightly Rust / Compiler Plugins

There are links pointing to rustc crates that end up to a 404 page:

• https://doc.rust-lang.org/stable/rustc_plugin*
• https://doc.rust-lang.org/stable/syntax*
• https://doc.rust-lang.org/stable/rustc*

Discussion on section 21: interior mutability

Slices:

From @aturon in #60

You should more explicitly mention that, by taking a slice, we can
work not just on a full string, but also on some view of it (with, as
you say, no loss in generality).

My thoughts:

Do you have any thoughts on how to be more explicit here? I thought this was already:

And we can take
a string slice that’s the full length of a String, so we haven’t lost
the ability to talk about full Strings. And additionally, we can take
string slices of string literals too, so this function is more useful, but
with no loss of functionality:

Maybe it's the focus around literals or something that makes it feel like it's not saying that?

Discussion on section 11: closures

Images have a white background even with dark themes

/cc @Mark-Simulacrum

We might be able to just make the background transparent, but then the black text would be tough.

@azerupi is there even a way to switch images based on theme? That's another solution.

Maybe use frames, anchors or JavaScript to persist sidebar position.

Every link in the sidebar is complete page refresh that resets the sidebar back to the top. It's very frustrating when you just want to quickly browse through all the topics in the syntax section. I can't just click through the sections quickly, I need to click, scroll the content, and then scroll the sidebar and repeat. If the content was in a frame the sidebar wouldn't be refreshed. Using a # anchor might be able to let you have the page load with the sidebar scrolled to the right position but it seems weird to use an anchor to do that for a sidebar. You could also use JavaScript to maintain sidebar position on a page load. Frames seems like what you want to use here though since that's exactly how the page is laid out. You could also just have all the content in one page load and use JavaScript to toggle what is being shown.

As it is, I'm opening separate tabs for the sidebar links to avoid having to scroll the sidebar back into position all the time, which is weird given the frame like layout.

Bad explanation in "Universal Function Call Syntax"

In section Angle-bracket Form, there is the following sentence:

The as Trait part is optional if it’s not ambiguous. Same with the angle brackets, hence the shorter form.

This is confusing, since it suggests there is only one abbreviated form, whereas in fact <Trait> is quite different from Type!

Markdown tables not rendered

I'm guessing it's a case of the markdown implementation not supporting tables?
For example the table in primitive types for integers.

Use of Result.expect() in Chapter 3

Were the examples in Chapter 3 written before the Result type had an expect method? There seem to be several cases where we rely on casting to Option with something like .ok().expect() or map_err().unwrap().

5.25. Crates and Modules: Add dependency to Cargo.toml

In 5.25. Crates and Modules: It is not clear that it is necessary to add something like the following to Cargo.toml:

[dependencies]
foo = { path = "/path/to/foo" }

Translate to pt-br

Hi there!

What do I need to do to start a translation to pt-br?

[Discussion] Structure

Hi Steve,

A couple of thoughts about the structure:

1. As of now, all source files reside in the root src folder. Do you plan on adding a bit more hierarchy? For example, every chapter / section could be moved into it's own directory, so that files about similar subjects reside closer to each other and are more easily found.

   src
   ├── 1-introduction
   │   ├── hello_worl.md
   │   ├── introduction.md
   │   └── ...
   ├── 2-tutorial
   │   ├── ...
   └── 3-primitive_rust
   │   ├── functions.md
   │   ├── variable_bindings.md
   │   └── ...
   ├── ...
   

2. The current version (old book) is pretty "flat", there is only one sub-level to the chapters. I would personally subdivide the longer chapters, were you have multiple sub-parts, into actual sub-chapters.

   Shorter chapters, focussing on one specific subject, are more comprehensive. You clearly see where the current subject stops and were the next begins. Reading a chapter feels lighter and less involved, which is good when you read on-the-go, in situations were your time is limited or when there is a lot of distraction.

   Because sub-chapters would be shown in the sidebar, it would also enhance the structure and navigation.

What is your view about this?

Discussion on section 12: Iterators

Can the book be downloaded as a PDF?

Sorry if this has already been asked or if this is already possible...

I know this question has been asked a few times before and it would be a great feature for someone like me who is offline when on the train heading to work, it would be a great use of my time to be able to read the Rust Book without needing internet connection.

Is there some sort of process which regularly takes the latest version and PDF's it for download online?

Move: graphics don't illustrate copying

@Mark-Simulacrum said:

The graphics illustrating moving don't appear to represent the copying of the data.

Could you elaborate a bit more on this specifics here, maybe

Discussion on section 17: Unsafe Rust

Discussion on section 8: Error handling

Discussion on section 3: Primitive Rust

Discussion on Section 20: Advanced Type System Features

Discussion on section 16: concurrency

Chapter 2.3 "Hello, Cargo": "rm" should be "del" on Windows

In paragraph "Converting to Cargo":

Is:
$ rm main # or 'rm main.exe' on Windows

Should be:
$ rm main # or 'del main.exe' on Windows"

(Unless there is an alias..)

Discussion on section 22: macros

make a bigger disclaimer about this being in-progress

So it doesn't confuse people.

Discussion on section 10: Traits

Discussion on section 7: Crates & Modules

Turn the book available offline

It would be interesting to have the book available in downloadable formats as mobi, epub or pdf for offline reading.

Discussion on section 14: Testing

Discussion on section 5: Structs