1 # The Rust Programming Language
3 [![Build Status](https://travis-ci.org/rust-lang/book.svg?branch=master)](https://travis-ci.org/rust-lang/book)
5 This repository contains the source of all editions of "the Rust Programming
8 The second edition will also be available in dead-tree form by No Starch
9 Press, available around May 2018. Check [the No Starch Page][nostarch] for
10 the latest information on the release date and how to order.
12 [nostarch]: https://nostarch.com/rust
14 You can read all editions of the book for free online! Please see the book as
15 shipped with the latest [stable], [beta], or [nightly] Rust releases. Be
16 aware that issues in those versions may have been fixed in this repository
17 already, as those releases are updated less frequently.
19 [stable]: https://doc.rust-lang.org/stable/book/
20 [beta]: https://doc.rust-lang.org/beta/book/
21 [nightly]: https://doc.rust-lang.org/nightly/book/
25 Building the book requires [mdBook], ideally the same version that
26 [rust-lang/rust uses in this file][rust-mdbook]. To get it:
28 [mdBook]: https://github.com/azerupi/mdBook
29 [rust-mdbook]: https://github.com/rust-lang/rust/blob/master/src/tools/rustbook/Cargo.toml
32 $ cargo install mdbook --vers [version-num]
37 To build the book, first `cd` into one of the directory of the edition of the
38 book you'd like to build. For example, the `first-edition` or
39 `second-edition` directory. Then type:
45 The output will be in the `book` subdirectory. To check it out, open it in
50 $ firefox book/index.html # Linux
51 $ open -a "Firefox" book/index.html # OS X
52 $ Start-Process "firefox.exe" .\book\index.html # Windows (PowerShell)
53 $ start firefox.exe .\book\index.html # Windows (Cmd)
58 $ google-chrome book/index.html # Linux
59 $ open -a "Google Chrome" book/index.html # OS X
60 $ Start-Process "chrome.exe" .\book\index.html # Windows (PowerShell)
61 $ start chrome.exe .\book\index.html # Windows (Cmd)
72 We'd love your help! Please see [CONTRIBUTING.md][contrib] to learn about the
73 kinds of contributions we're looking for.
77 The second edition of The Rust Programming Language is getting ever closer to being printed!
81 The first edition is frozen, and is not accepting any changes at this time.
84 [contrib]: https://github.com/rust-lang/book/blob/master/CONTRIBUTING.md
88 We'd especially love help translating the second edition of the book! See the
89 [Translations] label to join in efforts that are currently in progress. Open
90 a new issue to start working on a new language! We're waiting on [mdbook
91 support] for multiple languages before we merge any in, but feel free to
92 start! The chapters in [the frozen column] of the project won't see major
93 changes, so if you start with those, you won't have to redo work :)
95 [Translations]: https://github.com/rust-lang/book/issues?q=is%3Aopen+is%3Aissue+label%3ATranslations
96 [mdbook support]: https://github.com/azerupi/mdBook/issues/5
97 [the frozen column]: https://github.com/rust-lang/book/projects/1
101 As the second edition of the book will be published by No Starch, we first
102 iterate here, then ship the text off to No Starch. Then they do editing, and we
105 As such, there’s a directory, *nostarch*, which corresponds to the text in No
108 When we've started working with No Starch in a word doc, we will also check
109 those into the repo in the *nostarch/odt* directory. To extract the text from
110 the word doc as markdown in order to backport changes to the online book:
112 1. Open the doc file in LibreOffice
113 1. Accept all tracked changes
114 1. Save as Microsoft Word 2007-2013 XML (.docx) in the *tmp* directory
115 1. Run `./doc-to-md.sh`
116 1. Inspect changes made to the markdown file in the *nostarch* directory and
117 copy the changes to the *src* directory as appropriate.
121 We're using [Graphviz](http://graphviz.org/) for some of the diagrams in the
122 book. The source for those files live in the `dot` directory. To turn a `dot`
123 file, for example, `dot/trpl04-01.dot` into an `svg`, run:
126 $ dot dot/trpl04-01.dot -Tsvg > src/img/trpl04-01.svg
129 In the generated SVG, remove the width and the height attributes from the `svg`
130 element and set the `viewBox` attribute to `0.00 0.00 1000.00 1000.00` or other
131 values that don't cut off the image.
135 To scan source files for spelling errors, you can use the `spellcheck.sh`
136 script. It needs a dictionary of valid words, which is provided in
137 `dictionary.txt`. If the script produces a false positive (say, you used word
138 `BTreeMap` which the script considers invalid), you need to add this word to
139 `dictionary.txt` (keep the sorted order for consistency).