]>
Commit | Line | Data |
---|---|---|
8bb4bdeb | 1 | # The Rustonomicon |
c1a9b12d | 2 | |
dc9dc135 | 3 | #### The Dark Arts of Unsafe Rust |
450edc1f XL |
4 | |
5 | > THE KNOWLEDGE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, | |
6 | INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF UNLEASHING INDESCRIBABLE HORRORS THAT | |
7 | SHATTER YOUR PSYCHE AND SET YOUR MIND ADRIFT IN THE UNKNOWABLY INFINITE COSMOS. | |
c1a9b12d | 8 | |
dc9dc135 XL |
9 | The Rustonomicon digs into all the awful details that you need to understand when |
10 | writing Unsafe Rust programs. | |
11 | ||
c1a9b12d SL |
12 | Should you wish a long and happy career of writing Rust programs, you should |
13 | turn back now and forget you ever saw this book. It is not necessary. However | |
3b2f2976 XL |
14 | if you intend to write unsafe code — or just want to dig into the guts of the |
15 | language — this book contains lots of useful information. | |
16 | ||
17 | Unlike *[The Rust Programming Language][trpl]*, we will be assuming considerable | |
18 | prior knowledge. In particular, you should be comfortable with basic systems | |
19 | programming and Rust. If you don't feel comfortable with these topics, you | |
416331ca | 20 | should consider reading [The Book][trpl] first. That said, we won't assume you |
3b2f2976 XL |
21 | have read it, and we will take care to occasionally give a refresher on the |
22 | basics where appropriate. You can skip straight to this book if you want; | |
23 | just know that we won't be explaining everything from the ground up. | |
24 | ||
dc9dc135 XL |
25 | This book exists primarily as a high-level companion to [The Reference][ref]. |
26 | Where The Reference exists to detail the syntax and semantics of every part of | |
27 | the language, The Rustonomicon exists to describe how to use those pieces together, | |
28 | and the issues that you will have in doing so. | |
29 | ||
30 | The Reference will tell you the syntax and semantics of references, destructors, and | |
31 | unwinding, but it won't tell you how combining them can lead to exception-safety | |
32 | issues, or how to deal with those issues. | |
33 | ||
34 | It should be noted that when The Rustonomicon was originally written, The | |
35 | Reference was in a state of complete disrepair, and so many things that should | |
36 | have been covered by The Reference were originally only documented here. Since | |
37 | then, The Reference has been revitalized and is properly maintained, although | |
38 | it is still far from complete. In general, if the two documents disagree, The | |
39 | Reference should be assumed to be correct (it isn't yet considered normative, | |
40 | it's just better maintained). | |
41 | ||
42 | Topics that are within the scope of this book include: the meaning of (un)safety, | |
43 | unsafe primitives provided by the language and standard library, techniques for | |
44 | creating safe abstractions with those unsafe primitives, subtyping and variance, | |
45 | exception-safety (panic/unwind-safety), working with uninitialized memory, | |
46 | type punning, concurrency, interoperating with other languages (FFI), | |
47 | optimization tricks, how constructs lower to compiler/OS/hardware primitives, | |
48 | how to **not** make the memory model people angry, how you're **going** to make the | |
49 | memory model people angry, and more. | |
50 | ||
51 | The Rustonomicon is not a place to exhaustively describe the semantics and guarantees | |
52 | of every single API in the standard library, nor is it a place to exhaustively describe | |
53 | every feature of Rust. | |
c1a9b12d | 54 | |
3157f602 | 55 | [trpl]: ../book/index.html |
dc9dc135 | 56 | [ref]: ../reference/index.html |