Library

The library/ directory contains the Rust standard library and the runtime crates around it. Together these are what rustup install stable puts in your sysroot — core, alloc, std, proc_macro, test, plus a long tail of runtime support crates.

Pages in this section

• core — #![no_std] foundations (no allocator, no OS)
• alloc — heap-allocated types (Box, Vec, String, Rc, …)
• std — OS-level facilities (filesystem, threads, sockets, locks)
• Other runtime crates — proc_macro, test, panic_*, compiler-builtins, unwind, stdarch, portable-simd, backtrace

Layering

graph BT
    Cb["compiler-builtins<br/>(intrinsics)"] --> Core
    Core["core (#![no_std])"] --> Alloc
    Alloc["alloc"] --> Std
    Pu["panic_unwind / panic_abort"] --> Std
    Stdarch["stdarch (SIMD)"] --> Core
    Std["std"]
    Pm["proc_macro"] --> Std
    Test["test"] --> Std
    Unwind["unwind"] --> Std

The standard library's three main public crates form a strict layering:

• core — the freestanding minimum: primitive types, Option, Result, iterators, slice/str fundamentals, intrinsics. No allocator, no OS, no I/O. Must work in #![no_std] environments (kernels, embedded).
• alloc — adds one assumption: a global allocator. This unlocks Box, Vec, String, Rc, Arc, BTreeMap, HashMap (no — HashMap is in std), and friends.
• std — adds the host operating system: filesystem, processes, threads, sockets, env vars, command-line, time, sync primitives. The most-used crate; the one you get with extern crate std.

A #![no_std] crate can use core (and optionally alloc if it provides an allocator). Embedded targets and kernels typically use only core.

What's not in library/

A lot of "the standard library" lives outside this repo:

• cargo — separate repo, vendored as a submodule under src/tools/cargo/
• clippy, rustfmt, rust-analyzer, miri — separate repos, vendored as subtrees under src/tools/
• Most third-party crates — rand, serde, tokio, regex, log, … — live on crates.io
• rustc-demangle, gimli, addr2line, object — used by std internals but maintained separately

Vendored subtrees

Several library/ subdirectories are subtrees from external repos:

Path	Upstream
library/stdarch/	rust-lang/stdarch — SIMD intrinsics
library/portable-simd/	rust-lang/portable-simd — portable SIMD wrappers
library/backtrace/	rust-lang/backtrace-rs — backtrace symbolication
library/compiler-builtins/	rust-lang/compiler-builtins — software intrinsics

Changes to these go through the upstream repos first; they get pulled into rust-lang/rust periodically.

Workspace

library/ has its own Cargo.toml — it's a separate Cargo workspace from the compiler workspace. The reason: library/ crates are compiled with rustc as a build artifact, with carefully chosen feature flags and #[cfg(...)]s, and using a different sysroot. The two workspaces having different lockfiles avoids accidental coupling.

Building and testing

./x build library                    # build std/core/alloc with the stage-1 compiler
./x test library/std                 # run std unit tests
./x test library/core                # run core unit tests
./x doc --stage 0 library/std        # build rustdoc against stage 0 (fast)

For test infrastructure specific to library/ (and especially core and alloc), see the coretests/, alloctests/, and library/std/tests/ directories — these are separate test crates that use the public API of the libraries they test.

API stabilization

Items in library/* use the standard #[stable] / #[unstable] attribute machinery from rustc_feature. New API goes through:

1. RFC or libs-api ACP (API Change Proposal)
2. Implementation as #[unstable(feature = "...", issue = "...")]
3. Tracking issue lifecycle, including any redesigns
4. Final libs-api FCP for stabilization
5. Removal of the #[unstable] attribute (or change to #[stable])

The libs-api team owns the public API. Internal helpers don't need stabilization but should be pub(crate) or #[doc(hidden)] pub where possible.

Where to learn more

• The Rust standard library docs — the user-facing API reference
• The standard-library developer guide — the internal contributor handbook
• Patterns and conventions — repo-wide conventions