Merge pull request #217 from rust-lang/rust-1.36-37

update guide for 1.36 and 1.37

Author: steveklabnik

src/SUMMARY.md

@@ -99,4 +99,8 @@
     - [Pinning](rust-next/pin.md)
     - [No more FnBox](rust-next/no-more-fnbox.md)
     - [Alternative Cargo Registries](rust-next/alternative-cargo-registries.md)
-    - [TryFrom and TryInto](rust-next/tryfrom-and-tryinto.md)
+    - [TryFrom and TryInto](rust-next/tryfrom-and-tryinto.md)
+    - [The Future trait](rust-next/future.md)
+    - [The alloc crate](rust-next/alloc.md)
+    - [MaybeUninit<T>](rust-next/maybe-uninit.md)
+    - [cargo vendor](rust-next/cargo-vendor.md)

src/rust-next/alloc.md

@@ -0,0 +1,28 @@
+# The alloc crate
+
+Initially added: ![Minimum Rust version: 1.36](https://img.shields.io/badge/Minimum%20Rust%20Version-1.36-brightgreen.svg)
+
+Before 1.36.0, the standard library consisted of the crates `std`, `core`, and `proc_macro`.
+The `core` crate provided core functionality such as `Iterator` and `Copy`
+and could be used in `#![no_std]` environments since it did not impose any requirements.
+Meanwhile, the `std` crate provided types like `Box<T>` and OS functionality
+but required a global allocator and other OS capabilities in return.
+
+Starting with Rust 1.36.0, the parts of `std` that depend on a global allocator, e.g. `Vec<T>`,
+are now available in the `alloc` crate. The `std` crate then re-exports these parts.
+While `#![no_std]` *binaries* using `alloc` still require nightly Rust,
+`#![no_std]` *library* crates can use the `alloc` crate in stable Rust.
+Meanwhile, normal binaries, without `#![no_std]`, can depend on such library crates.
+We hope this will facilitate the development of a `#![no_std]` compatible ecosystem of libraries
+prior to stabilizing support for `#![no_std]` binaries using `alloc`.
+
+If you are the maintainer of a library that only relies on some allocation primitives to function,
+consider making your library `#[no_std]` compatible by using the following at the top of your `lib.rs` file:
+
+```rust,ignore
+#![no_std]
+
+extern crate alloc;
+
+use alloc::vec::Vec;
+```

src/rust-next/cargo-vendor.md

@@ -0,0 +1,9 @@
+# cargo vendor
+
+Initially added: ![Minimum Rust version: 1.37](https://img.shields.io/badge/Minimum%20Rust%20Version-1.37-brightgreen.svg)
+
+After being available [as a separate crate][vendor-crate] for years, the `cargo vendor` command is now integrated directly into Cargo. The command fetches all your project's dependencies unpacking them into the `vendor/` directory, and shows the configuration snippet required to use the vendored code during builds.
+
+There are multiple cases where `cargo vendor` is already used in production: the Rust compiler `rustc` uses it to ship all its dependencies in release tarballs, and projects with monorepos use it to commit the dependencies' code in source control.
+
+[vendor-crate]: https://crates.io/crates/cargo-vendor

src/rust-next/future.md

@@ -0,0 +1,10 @@
+# The Future trait
+
+Initially added: ![Minimum Rust version: 1.36](https://img.shields.io/badge/Minimum%20Rust%20Version-1.36-brightgreen.svg)
+
+In Rust 1.36.0 the long awaited [`Future`] trait has been stabilized!
+
+TODO: this will probably be folded into a larger async section once we're
+closer to the next edition.
+
+[`Future`]: https://doc.rust-lang.org/std/future/trait.Future.html

src/rust-next/maybe-uninit.md

@@ -0,0 +1,28 @@
+# MaybeUninit
+
+Initially added: ![Minimum Rust version: 1.36](https://img.shields.io/badge/Minimum%20Rust%20Version-1.36-brightgreen.svg)
+
+In previous releases of Rust, the [`mem::uninitialized`] function has allowed
+you to bypass Rust's initialization checks by pretending that you've
+initialized a value at type `T` without doing anything. One of the main uses
+of this function has been to lazily allocate arrays.
+
+However, [`mem::uninitialized`] is an incredibly dangerous operation that
+essentially cannot be used correctly as the Rust compiler assumes that values
+are properly initialized. For example, calling `mem::uninitialized::<bool>()`
+causes *instantaneous __undefined behavior__* as, from Rust's point of view,
+the uninitialized bits are neither `0` (for `false`) nor `1` (for `true`) -
+the only two allowed bit patterns for `bool`.
+
+To remedy this situation, in Rust 1.36.0, the type [`MaybeUninit<T>`] has
+been stabilized. The Rust compiler will understand that it should not assume
+that a [`MaybeUninit<T>`] is a properly initialized `T`. Therefore, you can
+do gradual initialization more safely and eventually use `.assume_init()`
+once you are certain that `maybe_t: MaybeUninit<T>` contains an initialized
+`T`.
+
+As [`MaybeUninit<T>`] is the safer alternative, starting with Rust 1.39, the
+function [`mem::uninitialized`] will be deprecated.
+
+[`MaybeUninit<T>`]: https://doc.rust-lang.org/std/mem/union.MaybeUninit.html
+[`mem::uninitialized`]: https://doc.rust-lang.org/std/mem/fn.uninitialized.html