[rustc.git] / src / doc / edition-guide / src / rust-next / alloc.md

# 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;
```
Commit	Line	Data
3dfed10e XL	1	# The alloc crate
	2
	3	Initially added: ![Minimum Rust version: 1.36](https://img.shields.io/badge/Minimum%20Rust%20Version-1.36-brightgreen.svg)
	4
	5	Before 1.36.0, the standard library consisted of the crates `std`, `core`, and `proc_macro`.
	6	The `core` crate provided core functionality such as `Iterator` and `Copy`
	7	and could be used in `#![no_std]` environments since it did not impose any requirements.
	8	Meanwhile, the `std` crate provided types like `Box<T>` and OS functionality
	9	but required a global allocator and other OS capabilities in return.
	10
	11	Starting with Rust 1.36.0, the parts of `std` that depend on a global allocator, e.g. `Vec<T>`,
	12	are now available in the `alloc` crate. The `std` crate then re-exports these parts.
	13	While `#![no_std]` binaries using `alloc` still require nightly Rust,
	14	`#![no_std]` library crates can use the `alloc` crate in stable Rust.
	15	Meanwhile, normal binaries, without `#![no_std]`, can depend on such library crates.
	16	We hope this will facilitate the development of a `#![no_std]` compatible ecosystem of libraries
	17	prior to stabilizing support for `#![no_std]` binaries using `alloc`.
	18
	19	If you are the maintainer of a library that only relies on some allocation primitives to function,
	20	consider making your library `#[no_std]` compatible by using the following at the top of your `lib.rs` file:
	21
	22	```rust,ignore
	23	#![no_std]
	24
	25	extern crate alloc;
	26
	27	use alloc::vec::Vec;
	28	```