This page provides an overview of how the Rust standard library is structured across three interdependent crates (core, alloc, std), what each layer provides, how they relate to each other, and how they are built into the sysroot. For details on specific subsystems, see:
Box, Rc, Arc, Vec, HashMap, etc.The Rust standard library is not a single crate. It is split across three crates organized in a strict dependency hierarchy, each serving a different target environment:
| Crate | Location | Description |
|---|---|---|
core | library/core/ | Dependency-free foundation. No heap, no OS, no libc. |
alloc | library/alloc/ | Heap allocation layer. Depends on core. |
std | library/std/ | Full standard library. Depends on core and alloc. |
All three crates are built as part of the sysroot — the set of libraries shipped alongside the compiler that every Rust program links against by default. The bootstrap build system compiles these crates from source during each compiler stage. For more on the build process, see Bootstrap Build System.
Crate dependency structure (library layer)
Sources: library/core/src/lib.rs1-50 library/alloc/src/lib.rs1-58 library/std/src/lib.rs433-460
core Cratecore is the bedrock of the entire library. It declares #![no_core] and #![no_std], meaning it links to nothing. It has no knowledge of heap allocation, threads, or operating systems.
library/core/src/lib.rs1-15 states the design intent explicitly: it is "the portable glue between the language and its libraries."
core Requires from the Environmentcore itself does not provide these — the host environment must supply them:
| Symbol | Purpose |
|---|---|
memcpy, memmove, memset, memcmp, bcmp, strlen | Memory routines; provided by libc or compiler_builtins |
#[panic_handler] | User-defined function called on panic; signature fn(&PanicInfo) -> ! |
rust_eh_personality | Exception handling personality function; lang item eh_personality |
coreCore module hierarchy
Sources: library/core/src/lib.rs259-388
corecore uses #[path = ...] attributes to inline two external repositories directly as modules:
core_arch — pulled from stdarch/crates/core_arch/src/mod.rs. Exposed as core::arch. Provides architecture-specific intrinsics (x86, ARM, etc.)core_simd — pulled from portable-simd/crates/core_simd/src/mod.rs. Exposed as core::simd. Provides the portable SIMD API.library/core/src/lib.rs344-385
core| Type | Module | Description |
|---|---|---|
Option<T> | core::option | Optional value |
Result<T, E> | core::result | Success/error value |
Cell<T>, RefCell<T>, UnsafeCell<T> | core::cell | Interior mutability |
NonZero<T> | core::num | Non-zero integer wrapper with niche optimization |
*const T, *mut T | core::ptr | Raw pointer operations |
NonNull<T> | core::ptr | Non-null raw pointer |
AtomicBool, AtomicUsize, etc. | core::sync::atomic | Atomic primitives |
[T] (slice) | core::slice | Slice operations |
str | core::str | UTF-8 string slice operations |
alloc Cratealloc introduces heap allocation on top of core. It is #![no_std] and #![needs_allocator], meaning it requires a global allocator to be present but does not assume an operating system.
library/alloc/src/lib.rs1-57 describes its role: smart pointers (Box, Rc, Arc), collections (Vec, String, BTreeMap), and heap interfaces.
Allocator TraitAll heap-using types in alloc are generic over an allocator type that implements core::alloc::Allocator. The default is alloc::alloc::Global, which calls the global allocator defined by the user program or runtime.
allocKey modules in alloc
Sources: library/alloc/src/lib.rs1-57 library/alloc/src/vec/mod.rs1-100 library/alloc/src/rc.rs1-50 library/alloc/src/sync.rs1-50 library/alloc/src/string.rs1-70
alloc| Type | File | Description |
|---|---|---|
Box<T, A> | alloc/src/boxed.rs | Unique heap ownership |
Rc<T> | alloc/src/rc.rs | Single-threaded reference-counted pointer |
Arc<T, A> | alloc/src/sync.rs | Thread-safe atomically reference-counted pointer |
Vec<T, A> | alloc/src/vec/mod.rs | Growable heap array |
String | alloc/src/string.rs | Growable UTF-8 string (backed by Vec<u8>) |
VecDeque<T> | alloc/src/collections/vec_deque/mod.rs | Double-ended queue |
BTreeMap<K, V> | alloc/src/collections/btree/map.rs | Ordered key-value map |
RawVec<T, A> | alloc/src/raw_vec.rs | Low-level heap buffer (used by Vec and VecDeque) |
Vec<T> Internal StructureVec<T> is defined as a (RawVec<T, A>, len: usize) pair. RawVec owns the heap allocation. library/alloc/src/vec/mod.rs438-441
ptr len capacity
+--------+--------+--------+
| 0x0123 | 2 | 4 |
+--------+--------+--------+
|
v
Heap +--------+--------+--------+--------+
| 'a' | 'b' | uninit | uninit |
+--------+--------+--------+--------+
Arc<T> Internal StructureArc<T> stores a NonNull<ArcInner<T>> where ArcInner<T> contains two atomic reference counts (strong, weak) and the data. library/alloc/src/sync.rs382-392
std Cratestd is the full standard library available to programs that target a known OS. It extends core and alloc with platform-dependent functionality: file I/O, networking, threads, environment access, and more.
std is #![no_std] in the sense that it does not depend on itself — it explicitly imports alloc as alloc_crate and re-exports its contents. library/std/src/lib.rs434-435
std contains a private sys module that provides OS-specific implementations for all platform-dependent operations. This module is not public API.
std| Crate | How | Purpose |
|---|---|---|
alloc | extern crate alloc as alloc_crate | Re-exports alloc types |
libc | extern crate libc | C library bindings |
unwind | extern crate unwind | Stack unwinding for backtraces |
backtrace (rs) | #[path = "../../backtrace/src/lib.rs"] | Backtrace symbolization |
portable-simd (std_float) | #[path = "../../portable-simd/crates/std_float/src/lib.rs"] | Float math for SIMD |
hashbrown | via std::collections::hash | HashMap/HashSet implementation |
std_detect | via std::arch | Runtime CPU feature detection |
stdThese modules do not exist in core or alloc:
| Module | Description |
|---|---|
std::fs | File system access |
std::io | I/O traits and standard streams |
std::net | TCP/UDP networking |
std::thread | Thread spawning and management |
std::process | Process spawning and exit |
std::env | Environment variables, arguments |
std::path | File path manipulation |
std::sync | Mutex, RwLock, Condvar, Barrier, Once, channels |
std::collections | Re-exports alloc collections + HashMap, HashSet |
std::backtrace | Backtrace capture |
std::alloc | Global allocator interface |
core and allocstd re-exports the majority of core and alloc APIs directly:
core::* modules (std::option, std::result, std::mem, std::ptr, std::iter, etc.)alloc modules (std::boxed, std::rc, std::vec, std::string, std::slice, etc.)Each crate defines a prelude module that is automatically imported into every module of every crate that uses it. The prelude is injected via the #[prelude_import] attribute.
Prelude injection chain
core has its own minimal prelude at core::prelude::rust_2024 (library/core/src/lib.rs200-204)std has a full prelude at std::prelude::rust_2024 (library/std/src/lib.rs421-427)#![no_std] crates use only core::prelude or no prelude at allno_std UsageCrates that target embedded or other restricted environments can opt out of std with #![no_std]. They still have access to core automatically. They can optionally depend on alloc if they provide a global allocator.
| Attribute | Effect |
|---|---|
| (none) | Links std (includes core and alloc) |
#![no_std] | Excludes std; core still available; alloc optional |
#![no_core] | Excludes even core; only used by core itself |
core itself is declared with #![no_core] library/core/src/lib.rs75 making it the one crate that has zero implicit library dependencies.
The three library crates are built as part of the sysroot during the bootstrap process. The bootstrap system compiles them at each compiler stage. The resulting .rlib files are placed in the sysroot so that user crates can link against them without specifying them explicitly.
For the full details of how the sysroot is assembled and how these crates are staged, see Bootstrap Build System.
Sysroot artifact structure
Sources: library/core/src/lib.rs1-50 library/alloc/src/lib.rs59-84 library/std/src/lib.rs216-240
Refresh this wiki
This wiki was recently refreshed. Please wait 4 days to refresh again.