diff --git a/mk/docs.mk b/mk/docs.mk index 3acc3c68b8f..a8ab6d55d7f 100644 --- a/mk/docs.mk +++ b/mk/docs.mk @@ -77,7 +77,7 @@ ERR_IDX_GEN = $(RPATH_VAR2_T_$(CFG_BUILD)_H_$(CFG_BUILD)) $(ERR_IDX_GEN_EXE) D := $(S)src/doc -DOC_TARGETS := trpl tarpl style error-index +DOC_TARGETS := trpl nomicon style error-index COMPILER_DOC_TARGETS := DOC_L10N_TARGETS := @@ -287,12 +287,12 @@ doc/book/index.html: $(RUSTBOOK_EXE) $(wildcard $(S)/src/doc/trpl/*.md) | doc/ $(Q)rm -rf doc/book $(Q)$(RUSTBOOK) build $(S)src/doc/trpl doc/book -tarpl: doc/adv-book/index.html +nomicon: doc/nomicon/index.html -doc/adv-book/index.html: $(RUSTBOOK_EXE) $(wildcard $(S)/src/doc/tarpl/*.md) | doc/ +doc/nomicon/index.html: $(RUSTBOOK_EXE) $(wildcard $(S)/src/doc/nomicon/*.md) | doc/ @$(call E, rustbook: $@) - $(Q)rm -rf doc/adv-book - $(Q)$(RUSTBOOK) build $(S)src/doc/tarpl doc/adv-book + $(Q)rm -rf doc/nomicon + $(Q)$(RUSTBOOK) build $(S)src/doc/nomicon doc/nomicon style: doc/style/index.html diff --git a/mk/tests.mk b/mk/tests.mk index c0962a1b0e7..9341166beb0 100644 --- a/mk/tests.mk +++ b/mk/tests.mk @@ -162,8 +162,8 @@ $(foreach doc,$(DOCS), \ $(eval $(call DOCTEST,md-$(doc),$(S)src/doc/$(doc).md))) $(foreach file,$(wildcard $(S)src/doc/trpl/*.md), \ $(eval $(call DOCTEST,$(file:$(S)src/doc/trpl/%.md=trpl-%),$(file)))) -$(foreach file,$(wildcard $(S)src/doc/tarpl/*.md), \ - $(eval $(call DOCTEST,$(file:$(S)src/doc/tarpl/%.md=tarpl-%),$(file)))) +$(foreach file,$(wildcard $(S)src/doc/nomicon/*.md), \ + $(eval $(call DOCTEST,$(file:$(S)src/doc/nomicon/%.md=nomicon-%),$(file)))) ###################################################################### # Main test targets ###################################################################### diff --git a/src/doc/nomicon/README.md b/src/doc/nomicon/README.md new file mode 100644 index 00000000000..4554652a17a --- /dev/null +++ b/src/doc/nomicon/README.md @@ -0,0 +1,38 @@ +% The Rustonomicon + +#### The Dark Arts of Advanced and Unsafe Rust Programming + +# NOTE: This is a draft document, and may contain serious errors + +> Instead of the programs I had hoped for, there came only a shuddering blackness +and ineffable loneliness; and I saw at last a fearful truth which no one had +ever dared to breathe before — the unwhisperable secret of secrets — The fact +that this language of stone and stridor is not a sentient perpetuation of Rust +as London is of Old London and Paris of Old Paris, but that it is in fact +quite unsafe, its sprawling body imperfectly embalmed and infested with queer +animate things which have nothing to do with it as it was in compilation. + +This book digs into all the awful details that are necessary to understand in +order to write correct Unsafe Rust programs. Due to the nature of this problem, +it may lead to unleashing untold horrors that shatter your psyche into a billion +infinitesimal fragments of despair. + +Should you wish a long and happy career of writing Rust programs, you should +turn back now and forget you ever saw this book. It is not necessary. However +if you intend to write unsafe code -- or just want to dig into the guts of the +language -- this book contains invaluable information. + +Unlike [The Book][trpl] we will be assuming considerable prior knowledge. In +particular, you should be comfortable with basic systems programming and Rust. +If you don't feel comfortable with these topics, you should consider [reading +The Book][trpl] first. Though we will not be assuming that you have, and will +take care to occasionally give a refresher on the basics where appropriate. You +can skip straight to this book if you want; just know that we won't be +explaining everything from the ground up. + +To be clear, this book goes into deep detail. We're going to dig into +exception-safety, pointer aliasing, memory models, and even some type-theory. +We will also be spending a lot of time talking about the different kinds +of safety and guarantees. + +[trpl]: ../book/ diff --git a/src/doc/tarpl/SUMMARY.md b/src/doc/nomicon/SUMMARY.md similarity index 100% rename from src/doc/tarpl/SUMMARY.md rename to src/doc/nomicon/SUMMARY.md diff --git a/src/doc/tarpl/arc-and-mutex.md b/src/doc/nomicon/arc-and-mutex.md similarity index 100% rename from src/doc/tarpl/arc-and-mutex.md rename to src/doc/nomicon/arc-and-mutex.md diff --git a/src/doc/tarpl/atomics.md b/src/doc/nomicon/atomics.md similarity index 100% rename from src/doc/tarpl/atomics.md rename to src/doc/nomicon/atomics.md diff --git a/src/doc/tarpl/borrow-splitting.md b/src/doc/nomicon/borrow-splitting.md similarity index 100% rename from src/doc/tarpl/borrow-splitting.md rename to src/doc/nomicon/borrow-splitting.md diff --git a/src/doc/tarpl/casts.md b/src/doc/nomicon/casts.md similarity index 100% rename from src/doc/tarpl/casts.md rename to src/doc/nomicon/casts.md diff --git a/src/doc/tarpl/checked-uninit.md b/src/doc/nomicon/checked-uninit.md similarity index 100% rename from src/doc/tarpl/checked-uninit.md rename to src/doc/nomicon/checked-uninit.md diff --git a/src/doc/tarpl/coercions.md b/src/doc/nomicon/coercions.md similarity index 100% rename from src/doc/tarpl/coercions.md rename to src/doc/nomicon/coercions.md diff --git a/src/doc/tarpl/concurrency.md b/src/doc/nomicon/concurrency.md similarity index 100% rename from src/doc/tarpl/concurrency.md rename to src/doc/nomicon/concurrency.md diff --git a/src/doc/tarpl/constructors.md b/src/doc/nomicon/constructors.md similarity index 100% rename from src/doc/tarpl/constructors.md rename to src/doc/nomicon/constructors.md diff --git a/src/doc/tarpl/conversions.md b/src/doc/nomicon/conversions.md similarity index 100% rename from src/doc/tarpl/conversions.md rename to src/doc/nomicon/conversions.md diff --git a/src/doc/tarpl/data.md b/src/doc/nomicon/data.md similarity index 100% rename from src/doc/tarpl/data.md rename to src/doc/nomicon/data.md diff --git a/src/doc/tarpl/destructors.md b/src/doc/nomicon/destructors.md similarity index 100% rename from src/doc/tarpl/destructors.md rename to src/doc/nomicon/destructors.md diff --git a/src/doc/tarpl/dot-operator.md b/src/doc/nomicon/dot-operator.md similarity index 100% rename from src/doc/tarpl/dot-operator.md rename to src/doc/nomicon/dot-operator.md diff --git a/src/doc/tarpl/drop-flags.md b/src/doc/nomicon/drop-flags.md similarity index 100% rename from src/doc/tarpl/drop-flags.md rename to src/doc/nomicon/drop-flags.md diff --git a/src/doc/tarpl/dropck.md b/src/doc/nomicon/dropck.md similarity index 100% rename from src/doc/tarpl/dropck.md rename to src/doc/nomicon/dropck.md diff --git a/src/doc/tarpl/exception-safety.md b/src/doc/nomicon/exception-safety.md similarity index 100% rename from src/doc/tarpl/exception-safety.md rename to src/doc/nomicon/exception-safety.md diff --git a/src/doc/tarpl/exotic-sizes.md b/src/doc/nomicon/exotic-sizes.md similarity index 100% rename from src/doc/tarpl/exotic-sizes.md rename to src/doc/nomicon/exotic-sizes.md diff --git a/src/doc/tarpl/hrtb.md b/src/doc/nomicon/hrtb.md similarity index 100% rename from src/doc/tarpl/hrtb.md rename to src/doc/nomicon/hrtb.md diff --git a/src/doc/tarpl/leaking.md b/src/doc/nomicon/leaking.md similarity index 100% rename from src/doc/tarpl/leaking.md rename to src/doc/nomicon/leaking.md diff --git a/src/doc/tarpl/lifetime-elision.md b/src/doc/nomicon/lifetime-elision.md similarity index 100% rename from src/doc/tarpl/lifetime-elision.md rename to src/doc/nomicon/lifetime-elision.md diff --git a/src/doc/tarpl/lifetime-mismatch.md b/src/doc/nomicon/lifetime-mismatch.md similarity index 100% rename from src/doc/tarpl/lifetime-mismatch.md rename to src/doc/nomicon/lifetime-mismatch.md diff --git a/src/doc/tarpl/lifetimes.md b/src/doc/nomicon/lifetimes.md similarity index 100% rename from src/doc/tarpl/lifetimes.md rename to src/doc/nomicon/lifetimes.md diff --git a/src/doc/tarpl/meet-safe-and-unsafe.md b/src/doc/nomicon/meet-safe-and-unsafe.md similarity index 100% rename from src/doc/tarpl/meet-safe-and-unsafe.md rename to src/doc/nomicon/meet-safe-and-unsafe.md diff --git a/src/doc/tarpl/obrm.md b/src/doc/nomicon/obrm.md similarity index 100% rename from src/doc/tarpl/obrm.md rename to src/doc/nomicon/obrm.md diff --git a/src/doc/tarpl/other-reprs.md b/src/doc/nomicon/other-reprs.md similarity index 100% rename from src/doc/tarpl/other-reprs.md rename to src/doc/nomicon/other-reprs.md diff --git a/src/doc/tarpl/ownership.md b/src/doc/nomicon/ownership.md similarity index 100% rename from src/doc/tarpl/ownership.md rename to src/doc/nomicon/ownership.md diff --git a/src/doc/tarpl/phantom-data.md b/src/doc/nomicon/phantom-data.md similarity index 100% rename from src/doc/tarpl/phantom-data.md rename to src/doc/nomicon/phantom-data.md diff --git a/src/doc/tarpl/poisoning.md b/src/doc/nomicon/poisoning.md similarity index 100% rename from src/doc/tarpl/poisoning.md rename to src/doc/nomicon/poisoning.md diff --git a/src/doc/tarpl/races.md b/src/doc/nomicon/races.md similarity index 100% rename from src/doc/tarpl/races.md rename to src/doc/nomicon/races.md diff --git a/src/doc/tarpl/references.md b/src/doc/nomicon/references.md similarity index 100% rename from src/doc/tarpl/references.md rename to src/doc/nomicon/references.md diff --git a/src/doc/tarpl/repr-rust.md b/src/doc/nomicon/repr-rust.md similarity index 100% rename from src/doc/tarpl/repr-rust.md rename to src/doc/nomicon/repr-rust.md diff --git a/src/doc/tarpl/safe-unsafe-meaning.md b/src/doc/nomicon/safe-unsafe-meaning.md similarity index 100% rename from src/doc/tarpl/safe-unsafe-meaning.md rename to src/doc/nomicon/safe-unsafe-meaning.md diff --git a/src/doc/tarpl/send-and-sync.md b/src/doc/nomicon/send-and-sync.md similarity index 100% rename from src/doc/tarpl/send-and-sync.md rename to src/doc/nomicon/send-and-sync.md diff --git a/src/doc/tarpl/subtyping.md b/src/doc/nomicon/subtyping.md similarity index 100% rename from src/doc/tarpl/subtyping.md rename to src/doc/nomicon/subtyping.md diff --git a/src/doc/tarpl/transmutes.md b/src/doc/nomicon/transmutes.md similarity index 100% rename from src/doc/tarpl/transmutes.md rename to src/doc/nomicon/transmutes.md diff --git a/src/doc/tarpl/unbounded-lifetimes.md b/src/doc/nomicon/unbounded-lifetimes.md similarity index 100% rename from src/doc/tarpl/unbounded-lifetimes.md rename to src/doc/nomicon/unbounded-lifetimes.md diff --git a/src/doc/tarpl/unchecked-uninit.md b/src/doc/nomicon/unchecked-uninit.md similarity index 100% rename from src/doc/tarpl/unchecked-uninit.md rename to src/doc/nomicon/unchecked-uninit.md diff --git a/src/doc/tarpl/uninitialized.md b/src/doc/nomicon/uninitialized.md similarity index 100% rename from src/doc/tarpl/uninitialized.md rename to src/doc/nomicon/uninitialized.md diff --git a/src/doc/tarpl/unwinding.md b/src/doc/nomicon/unwinding.md similarity index 100% rename from src/doc/tarpl/unwinding.md rename to src/doc/nomicon/unwinding.md diff --git a/src/doc/tarpl/vec-alloc.md b/src/doc/nomicon/vec-alloc.md similarity index 100% rename from src/doc/tarpl/vec-alloc.md rename to src/doc/nomicon/vec-alloc.md diff --git a/src/doc/tarpl/vec-dealloc.md b/src/doc/nomicon/vec-dealloc.md similarity index 100% rename from src/doc/tarpl/vec-dealloc.md rename to src/doc/nomicon/vec-dealloc.md diff --git a/src/doc/tarpl/vec-deref.md b/src/doc/nomicon/vec-deref.md similarity index 100% rename from src/doc/tarpl/vec-deref.md rename to src/doc/nomicon/vec-deref.md diff --git a/src/doc/tarpl/vec-drain.md b/src/doc/nomicon/vec-drain.md similarity index 100% rename from src/doc/tarpl/vec-drain.md rename to src/doc/nomicon/vec-drain.md diff --git a/src/doc/tarpl/vec-final.md b/src/doc/nomicon/vec-final.md similarity index 100% rename from src/doc/tarpl/vec-final.md rename to src/doc/nomicon/vec-final.md diff --git a/src/doc/tarpl/vec-insert-remove.md b/src/doc/nomicon/vec-insert-remove.md similarity index 100% rename from src/doc/tarpl/vec-insert-remove.md rename to src/doc/nomicon/vec-insert-remove.md diff --git a/src/doc/tarpl/vec-into-iter.md b/src/doc/nomicon/vec-into-iter.md similarity index 100% rename from src/doc/tarpl/vec-into-iter.md rename to src/doc/nomicon/vec-into-iter.md diff --git a/src/doc/tarpl/vec-layout.md b/src/doc/nomicon/vec-layout.md similarity index 100% rename from src/doc/tarpl/vec-layout.md rename to src/doc/nomicon/vec-layout.md diff --git a/src/doc/tarpl/vec-push-pop.md b/src/doc/nomicon/vec-push-pop.md similarity index 100% rename from src/doc/tarpl/vec-push-pop.md rename to src/doc/nomicon/vec-push-pop.md diff --git a/src/doc/tarpl/vec-raw.md b/src/doc/nomicon/vec-raw.md similarity index 100% rename from src/doc/tarpl/vec-raw.md rename to src/doc/nomicon/vec-raw.md diff --git a/src/doc/tarpl/vec-zsts.md b/src/doc/nomicon/vec-zsts.md similarity index 100% rename from src/doc/tarpl/vec-zsts.md rename to src/doc/nomicon/vec-zsts.md diff --git a/src/doc/tarpl/vec.md b/src/doc/nomicon/vec.md similarity index 100% rename from src/doc/tarpl/vec.md rename to src/doc/nomicon/vec.md diff --git a/src/doc/tarpl/working-with-unsafe.md b/src/doc/nomicon/working-with-unsafe.md similarity index 100% rename from src/doc/tarpl/working-with-unsafe.md rename to src/doc/nomicon/working-with-unsafe.md diff --git a/src/doc/tarpl/README.md b/src/doc/tarpl/README.md deleted file mode 100644 index e4a46827f46..00000000000 --- a/src/doc/tarpl/README.md +++ /dev/null @@ -1,34 +0,0 @@ -% The Advanced Rust Programming Language - -# NOTE: This is a draft document, and may contain serious errors - -So you've played around with Rust a bit. You've written a few simple programs -and you think you grok the basics. Maybe you've even read through *[The Rust -Programming Language][trpl]* (TRPL). Now you want to get neck-deep in all the -nitty-gritty details of the language. You want to know those weird corner-cases. -You want to know what the heck `unsafe` really means, and how to properly use -it. This is the book for you. - -To be clear, this book goes into serious detail. We're going to dig into -exception-safety and pointer aliasing. We're going to talk about memory -models. We're even going to do some type-theory. This is stuff that you -absolutely don't need to know to write fast and safe Rust programs. -You could probably close this book *right now* and still have a productive -and happy career in Rust. - -However if you intend to write unsafe code -- or just really want to dig into -the guts of the language -- this book contains invaluable information. - -Unlike TRPL we will be assuming considerable prior knowledge. In particular, you -should be comfortable with basic systems programming and basic Rust. If you -don't feel comfortable with these topics, you should consider [reading -TRPL][trpl], though we will not be assuming that you have. You can skip -straight to this book if you want; just know that we won't be explaining -everything from the ground up. - -Due to the nature of advanced Rust programming, we will be spending a lot of -time talking about *safety* and *guarantees*. In particular, a significant -portion of the book will be dedicated to correctly writing and understanding -Unsafe Rust. - -[trpl]: ../book/