Thanks to visit codestin.com
Credit goes to chromium.googlesource.com

Google Git
Sign in
chromium / external / github.com / rust-lang / rust / HEAD / . / src / doc / index.md
blob: 8ad5b427b552ae941b1ea0c92408410c4ac8c854 [file] [log] [blame] [view]
Brian Andersonfe13a9f2014-08-01 23:31:22[diff] [blame]1% Rust Documentation
Alan Andradee53b5662013-12-23 02:21:45[diff] [blame]2
Brian Anderson9e99a272015-12-23 22:15:13[diff] [blame]3<style>
4nav {
5 display: none;
6}
Trevor Gross4ecf1432023-01-19 07:03:10[diff] [blame]7h3 {
8 font-size: 1.35rem;
9}
10h4 {
11 font-size: 1.1rem;
12}
13
14/* Formatting for docs search bar */
Guillaume Gomez9d5ca392018-09-16 19:22:32[diff] [blame]15#search-input {
16 width: calc(100% - 58px);
17}
18#search-but {
19 cursor: pointer;
20}
21#search-but, #search-input {
22 padding: 4px;
23 border: 1px solid #ccc;
24 border-radius: 3px;
25 outline: none;
26 font-size: 0.7em;
27 background-color: #fff;
28}
29#search-but:hover, #search-input:focus {
30 border-color: #55a9ff;
31}
Trevor Gross4ecf1432023-01-19 07:03:10[diff] [blame]32
33/* Formatting for external link icon */
34svg.external-link {
35 display: inline-block;
36 position: relative;
37 vertical-align: super;
38 width: 0.7rem;
39 height: 0.7rem;
40 padding-left: 2px;
41 top: 3px;
Who? Me?!28cc9442018-11-19 21:50:24[diff] [blame]42}
Brian Anderson9e99a272015-12-23 22:15:13[diff] [blame]43</style>
Alan Andradee53b5662013-12-23 02:21:45[diff] [blame]44
Trevor Gross4ecf1432023-01-19 07:03:10[diff] [blame]45Welcome to an overview of the documentation provided by the [Rust
46project]. This page contains links to various helpful references,
47most of which are available offline (if opened with `rustup doc`). Many of these
48resources take the form of "books"; we collectively call these "The Rust
49Bookshelf." Some are large, some are small.
Steve Klabnik124b80a2014-08-28 18:52:39[diff] [blame]50
Trevor Gross4ecf1432023-01-19 07:03:10[diff] [blame]51All of these books are managed by the Rust Organization, but other unofficial
52documentation resources are included here as well!
Steve Klabnik124b80a2014-08-28 18:52:39[diff] [blame]53
Trevor Gross4ecf1432023-01-19 07:03:10[diff] [blame]54If you're just looking for the standard library reference, here it is:
55[Rust API documentation](std/index.html)
Steve Klabnik124b80a2014-08-28 18:52:39[diff] [blame]56
Trevor Gross4ecf1432023-01-19 07:03:10[diff] [blame]57
58## Learning Rust
59
60If you'd like to learn Rust, this is the section for you! All of these resources
steveklabnik77b570f2018-04-03 16:38:53[diff] [blame]61assume that you have programmed before, but not in any specific language:
62
Trevor Gross4ecf1432023-01-19 07:03:10[diff] [blame]63### The Rust Programming Language
steveklabnik77b570f2018-04-03 16:38:53[diff] [blame]64
Trevor Gross4ecf1432023-01-19 07:03:10[diff] [blame]65Affectionately nicknamed "the book," [The Rust Programming Language](book/index.html)
66will give you an overview of the language from first principles. You'll build a
67few projects along the way, and by the end, you'll have a solid grasp of how to
68use the language.
steveklabnik77b570f2018-04-03 16:38:53[diff] [blame]69
Trevor Gross4ecf1432023-01-19 07:03:10[diff] [blame]70### Rust By Example
steveklabnik77b570f2018-04-03 16:38:53[diff] [blame]71
72If reading multiple hundreds of pages about a language isn't your style, then
Trevor Gross4ecf1432023-01-19 07:03:10[diff] [blame]73[Rust By Example](rust-by-example/index.html) has you covered. RBE shows off a
74bunch of code without using a lot of words. It also includes exercises!
steveklabnik77b570f2018-04-03 16:38:53[diff] [blame]75
Trevor Gross4ecf1432023-01-19 07:03:10[diff] [blame]76### Rustlings
liv014ffa32019-02-05 14:32:59[diff] [blame]77
Trevor Gross4ecf1432023-01-19 07:03:10[diff] [blame]78[Rustlings](https://github.com/rust-lang/rustlings) guides you
79through downloading and setting up the Rust toolchain, then provides an
80interactive tool that teaches you how to solve coding challenges in Rust.
liv014ffa32019-02-05 14:32:59[diff] [blame]81
Trevor Gross4ecf1432023-01-19 07:03:10[diff] [blame]82### Rust Playground
steveklabnik77b570f2018-04-03 16:38:53[diff] [blame]83
Trevor Gross4ecf1432023-01-19 07:03:10[diff] [blame]84The [Rust Playground](https://play.rust-lang.org) is a great place
85to try out and share small bits of code, or experiment with some of the most
86popular crates.
steveklabnik77b570f2018-04-03 16:38:53[diff] [blame]87
steveklabnik77b570f2018-04-03 16:38:53[diff] [blame]88
Trevor Gross4ecf1432023-01-19 07:03:10[diff] [blame]89## Using Rust
90
91Once you've gotten familiar with the language, these resources can help you put
92it to work.
93
94### The Standard Library
95
96Rust's standard library has [extensive API documentation](std/index.html), with
97explanations of how to use various things, as well as example code for
98accomplishing various tasks. Code examples have a "Run" button on hover that
99opens the sample in the playground.
steveklabnik77b570f2018-04-03 16:38:53[diff] [blame]100
Kazuyoshi Katod63fd462018-09-15 06:28:32[diff] [blame]101<div>
102 <form action="std/index.html" method="get">
Guillaume Gomez9d5ca392018-09-16 19:22:32[diff] [blame]103 <input id="search-input" type="search" name="search"
104 placeholder="Search through the standard library"/>
105 <button id="search-but">Search</button>
Kazuyoshi Katod63fd462018-09-15 06:28:32[diff] [blame]106 </form>
107</div>
108
Trevor Gross4ecf1432023-01-19 07:03:10[diff] [blame]109### Your Personal Documentation
Siddhartha Sahu84a89aa2019-01-29 22:30:49[diff] [blame]110
Trevor Gross4ecf1432023-01-19 07:03:10[diff] [blame]111Whenever you are working in a crate, `cargo doc --open` will generate
112documentation for your project _and_ all its dependencies in their correct
113version, and open it in your browser. Add the flag `--document-private-items` to
114also show items not marked `pub`.
Siddhartha Sahu84a89aa2019-01-29 22:30:49[diff] [blame]115
Michael Howell29f5d2c2023-11-13 22:09:24[diff] [blame]116### Rust Version History
117
118[The Release Notes](releases.html) describes the change history of the Rust
119toolchain and language.
steveklabnik7de5b602018-04-05 18:53:58[diff] [blame]120
Trevor Gross4ecf1432023-01-19 07:03:10[diff] [blame]121[The Edition Guide](edition-guide/index.html) describes the Rust editions and
Michael Howell29f5d2c2023-11-13 22:09:24[diff] [blame]122their differences. The latest version of the toolchain supports all
123historical editions.
steveklabnik7de5b602018-04-05 18:53:58[diff] [blame]124
Trevor Gross4ecf1432023-01-19 07:03:10[diff] [blame]125### The `rustc` Book
steveklabnik77b570f2018-04-03 16:38:53[diff] [blame]126
Trevor Gross4ecf1432023-01-19 07:03:10[diff] [blame]127[The `rustc` Book](rustc/index.html) describes the Rust compiler, `rustc`.
steveklabnik77b570f2018-04-03 16:38:53[diff] [blame]128
Trevor Gross4ecf1432023-01-19 07:03:10[diff] [blame]129### The Cargo Book
130
131[The Cargo Book](cargo/index.html) is a guide to Cargo, Rust's build tool and
132dependency manager.
133
134### The Rustdoc Book
steveklabnik77b570f2018-04-03 16:38:53[diff] [blame]135
136[The Rustdoc Book](rustdoc/index.html) describes our documentation tool, `rustdoc`.
137
Trevor Gross4ecf1432023-01-19 07:03:10[diff] [blame]138### The Clippy Book
Philipp Krones665d7072022-07-06 08:01:03[diff] [blame]139
140[The Clippy Book](clippy/index.html) describes our static analyzer, Clippy.
141
Trevor Gross4ecf1432023-01-19 07:03:10[diff] [blame]142### Extended Error Listing
Brian Andersonbcf20a72016-01-10 22:30:09[diff] [blame]143
Steve Klabnik78dd2ec2017-02-07 18:04:57[diff] [blame]144Many of Rust's errors come with error codes, and you can request extended
Trevor Gross4ecf1432023-01-19 07:03:10[diff] [blame]145diagnostics from the compiler on those errors (with `rustc --explain`). You can
146also read them here if you prefer: [rustc error codes](error_codes/index.html)
Steve Klabnikacd84c22017-02-06 20:05:37[diff] [blame]147
Trevor Gross4ecf1432023-01-19 07:03:10[diff] [blame]148
149## Mastering Rust
Steve Klabnikacd84c22017-02-06 20:05:37[diff] [blame]150
steveklabnik77b570f2018-04-03 16:38:53[diff] [blame]151Once you're quite familiar with the language, you may find these advanced
152resources useful.
Steve Klabnikacd84c22017-02-06 20:05:37[diff] [blame]153
Trevor Gross4ecf1432023-01-19 07:03:10[diff] [blame]154### The Reference
Steve Klabnik55c02f62017-02-16 01:37:06[diff] [blame]155
Trevor Gross4ecf1432023-01-19 07:03:10[diff] [blame]156[The Reference](reference/index.html) is not a formal spec, but is more detailed
157and comprehensive than the book.
steveklabnikdce33e92017-04-25 09:35:51[diff] [blame]158
Trevor Gross4ecf1432023-01-19 07:03:10[diff] [blame]159### The Style Guide
Josh Triplett39484ac2022-09-24 16:20:23[diff] [blame]160
Trevor Gross4ecf1432023-01-19 07:03:10[diff] [blame]161[The Rust Style Guide](style-guide/index.html) describes the standard formatting
162of Rust code. Most developers use `cargo fmt` to invoke `rustfmt` and format the
163code automatically (the result matches this style guide).
Josh Triplett39484ac2022-09-24 16:20:23[diff] [blame]164
Trevor Gross4ecf1432023-01-19 07:03:10[diff] [blame]165### The Rustonomicon
Steve Klabnikacd84c22017-02-06 20:05:37[diff] [blame]166
Trevor Gross4ecf1432023-01-19 07:03:10[diff] [blame]167[The Rustonomicon](nomicon/index.html) is your guidebook to the dark arts of
168unsafe Rust. It's also sometimes called "the 'nomicon."
Brian Andersonbcf20a72016-01-10 22:30:09[diff] [blame]169
Trevor Gross4ecf1432023-01-19 07:03:10[diff] [blame]170### The Unstable Book
steveklabnik77b570f2018-04-03 16:38:53[diff] [blame]171
Trevor Gross4ecf1432023-01-19 07:03:10[diff] [blame]172[The Unstable Book](unstable-book/index.html) has documentation for unstable
173features.
Who? Me?!10a520a2018-11-19 21:45:19[diff] [blame]174
Trevor Gross4ecf1432023-01-19 07:03:10[diff] [blame]175### The `rustc` Contribution Guide
Who? Me?!10a520a2018-11-19 21:45:19[diff] [blame]176
Trevor Gross4ecf1432023-01-19 07:03:10[diff] [blame]177[The `rustc` Guide](https://rustc-dev-guide.rust-lang.org/)
178documents how the compiler works and how to contribute to it. This is useful if
179you want to build or modify the Rust compiler from source (e.g. to target
180something non-standard).
James Munns606e5e02019-01-19 03:52:39[diff] [blame]181
James Munns606e5e02019-01-19 03:52:39[diff] [blame]182
Trevor Gross4ecf1432023-01-19 07:03:10[diff] [blame]183## Specialized Rust
James Munns606e5e02019-01-19 03:52:39[diff] [blame]184
Trevor Gross4ecf1432023-01-19 07:03:10[diff] [blame]185When using Rust in specific domains, consider using the following resources
186tailored to each area.
James Munns606e5e02019-01-19 03:52:39[diff] [blame]187
Trevor Gross4ecf1432023-01-19 07:03:10[diff] [blame]188### Embedded Systems
189
190When developing for Bare Metal or Embedded Linux systems, you may find these
191resources maintained by the [Embedded Working Group] useful.
James Munns606e5e02019-01-19 03:52:39[diff] [blame]192
193[Embedded Working Group]: https://github.com/rust-embedded
194
Trevor Gross4ecf1432023-01-19 07:03:10[diff] [blame]195#### The Embedded Rust Book
James Munns606e5e02019-01-19 03:52:39[diff] [blame]196
Trevor Gross4ecf1432023-01-19 07:03:10[diff] [blame]197[The Embedded Rust Book] is targeted at developers familiar with embedded
198development and familiar with Rust, but have not used Rust for embedded
199development.
James Munns606e5e02019-01-19 03:52:39[diff] [blame]200
201[The Embedded Rust Book]: embedded-book/index.html
Guillaume Gomez8db2bf22020-11-04 10:06:42[diff] [blame]202[Rust project]: https://www.rust-lang.org
Trevor Gross4ecf1432023-01-19 07:03:10[diff] [blame]203
204<script>
205// check if a given link is external
206function isExternalLink(url) {
207 const tmp = document.createElement('a');
208 tmp.href = url;
209 return tmp.host !== window.location.host;
210}
211
212// Add the `external` class to all <a> tags with external links and append the external link SVG
213function updateExternalAnchors() {
214 /*
215 External link SVG from Font-Awesome
216 CC BY-SA 3.0 https://creativecommons.org/licenses/by-sa/3.0
217 via Wikimedia Commons
218 */
219 const svgText = `<svg
220 class='external-link'
221 xmlns='http://www.w3.org/2000/svg'
222 viewBox='0 -256 1850 1850'
223 width='100%'
224 height='100%'>
225 <g transform='matrix(1,0,0,-1,30,1427)'>
226 <path d='M 1408,608 V 288 Q 1408,169 1323.5,84.5 1239,0 1120,
227 0 H 288 Q 169,0 84.5,84.5 0,169 0,288 v 832 Q 0,1239 84.5,1323.5 169,
228 1408 288,1408 h 704 q 14,0 23,-9 9,-9 9,-23 v -64 q 0,-14 -9,-23 -9,
229 -9 -23,-9 H 288 q -66,0 -113,-47 -47,-47 -47,-113 V 288 q 0,-66 47,
230 -113 47,-47 113,-47 h 832 q 66,0 113,47 47,47 47,113 v 320 q 0,14 9,
231 23 9,9 23,9 h 64 q 14,0 23,-9 9,-9 9,-23 z m 384,864 V 960 q 0,
232 -26 -19,-45 -19,-19 -45,-19 -26,0 -45,19 L 1507,1091 855,439 q -10,
233 -10 -23,-10 -13,0 -23,10 L 695,553 q -10,10 -10,23 0,13 10,23 l 652,
234 652 -176,176 q -19,19 -19,45 0,26 19,45 19,19 45,19 h 512 q 26,0 45,
235 -19 19,-19 19,-45 z' style='fill:currentColor' />
236 </g>
237 </svg>`;
238 let allAnchors = document.getElementsByTagName("a");
239
240 for (var i = 0; i < allAnchors.length; ++i) {
241 let anchor = allAnchors[i];
242 if (isExternalLink(anchor.href)) {
243 anchor.classList.add("external");
244 anchor.innerHTML += svgText;
245 }
246 }
247}
248
249// on page load, update external anchors
250document.addEventListener("DOMContentLoaded", updateExternalAnchors);
251
252</script>