src/doc/nomicon/README.md

   1 % The Rustonomicon
   2
   3 #### The Dark Arts of Advanced and Unsafe Rust Programming
   4
   5 # NOTE: This is a draft document, and may contain serious errors
   6
   7 > Instead of the programs I had hoped for, there came only a shuddering blackness
   8 and ineffable loneliness; and I saw at last a fearful truth which no one had
   9 ever dared to breathe before — the unwhisperable secret of secrets — The fact
  10 that this language of stone and stridor is not a sentient perpetuation of Rust
  11 as London is of Old London and Paris of Old Paris, but that it is in fact
  12 quite unsafe, its sprawling body imperfectly embalmed and infested with queer
  13 animate things which have nothing to do with it as it was in compilation.
  14
  15 This book digs into all the awful details that are necessary to understand in
  16 order to write correct Unsafe Rust programs. Due to the nature of this problem,
  17 it may lead to unleashing untold horrors that shatter your psyche into a billion
  18 infinitesimal fragments of despair.
  19
  20 Should you wish a long and happy career of writing Rust programs, you should
  21 turn back now and forget you ever saw this book. It is not necessary. However
  22 if you intend to write unsafe code -- or just want to dig into the guts of the
  23 language -- this book contains invaluable information.
  24
  25 Unlike [The Book][trpl] we will be assuming considerable prior knowledge. In
  26 particular, you should be comfortable with basic systems programming and Rust.
  27 If you don't feel comfortable with these topics, you should consider [reading
  28 The Book][trpl] first. Though we will not be assuming that you have, and will
  29 take care to occasionally give a refresher on the basics where appropriate. You
  30 can skip straight to this book if you want; just know that we won't be
  31 explaining everything from the ground up.
  32
  33 To be clear, this book goes into deep detail. We're going to dig into
  34 exception-safety, pointer aliasing, memory models, and even some type-theory.
  35 We will also be spending a lot of time talking about the different kinds
  36 of safety and guarantees.
  37
  38 [trpl]: ../book/