rust-lang/rust

core

library/core/ is Rust's freestanding standard library — it makes no assumption about an allocator, an operating system, or any I/O. Every Rust program implicitly imports core::prelude::*; #![no_std] crates use core directly.

Purpose

core provides the primitives every Rust program needs:

Primitive type traits (Add, Sub, Iterator, From, Drop, Copy, Clone, …)
Optional / fallible types (Option, Result)
Iterators
Slice and str operations (the operations, not heap-backed strings)
Numeric types and methods
Pin, Future, async/await machinery
Atomic types (AtomicBool, AtomicUsize, …)
panic! (in its core form — different runtime in std)
mem, ptr, cell, marker, convert, cmp, ops modules
Intrinsics (the bridge to compiler-internal operations)
Formatting machinery (fmt::Display, fmt::Debug, write!)

Directory layout

library/core/
├── Cargo.toml
├── src/
│   ├── lib.rs                # Crate root
│   ├── intrinsics/           # Compiler intrinsics (pub fn linked to compiler)
│   ├── num/                  # Integer/float methods
│   ├── slice/                # &[T] operations
│   ├── str/                  # &str operations
│   ├── iter/                 # Iterator + IntoIterator + adapters
│   ├── ops/                  # operator traits (Add, Index, …)
│   ├── cmp.rs                # PartialOrd, Ord, Eq, …
│   ├── option.rs             # Option<T>
│   ├── result.rs             # Result<T, E>
│   ├── ptr/                  # Raw pointer ops
│   ├── mem/                  # mem::swap, replace, …
│   ├── cell.rs               # Cell, RefCell, OnceCell
│   ├── future/               # Future + AsyncContext primitives
│   ├── pin.rs                # Pin<P>
│   ├── marker.rs             # Send, Sync, Sized, Copy markers
│   ├── sync/atomic.rs        # AtomicXXX
│   ├── alloc/                # Layout, AllocError (no actual allocation)
│   ├── any.rs                # Any, TypeId
│   ├── panicking.rs          # panic-handling glue
│   ├── unicode/              # Generated Unicode tables
│   ├── prelude/              # The prelude
│   └── ...
└── tests/                    # Unit tests (in coretests/, technically)

Key abstractions

Type / trait	Where	Purpose
`Option<T>`	`core::option`	Nullable value
`Result<T, E>`	`core::result`	Fallible value
`Iterator`	`core::iter`	Pull-based iteration
`IntoIterator`	`core::iter`	Things you can iterate
`Pin<P>`	`core::pin`	Pinning of self-referential futures
`Future`	`core::future`	Future trait (pre-`async`/`await` glue)
`Cell<T>`, `RefCell<T>`	`core::cell`	Interior mutability
`OnceCell<T>`	`core::cell`	Write-once cell (no sync)
`Layout`	`core::alloc`	Allocation layout (size + align)
`Send`, `Sync`, `Sized`	`core::marker`	Auto-trait markers
`TypeId`, `Any`	`core::any`	Dynamic type identification
`AtomicUsize` and friends	`core::sync::atomic`	Hardware atomics

Intrinsics

core::intrinsics is the boundary between Rust and the compiler. Examples:

core::intrinsics::transmute — bitwise reinterpret (the public mem::transmute is built on this)
core::intrinsics::size_of_val_raw — mem::size_of_val for raw pointers
core::intrinsics::offset — pointer arithmetic primitive
core::intrinsics::copy_nonoverlapping — memcpy

Most intrinsics are unsafe; the core API wraps them in safe abstractions (mem::size_of, ptr::copy_nonoverlapping, …). Some are specifically implemented by the compiler — they don't have Rust bodies. Others have Rust bodies that the compiler may replace with intrinsic implementations on platforms where it makes sense.

How it works

core is built with the same compiler that builds the rest of library/. There's a careful dance between the compiler and core:

Some compiler intrinsics expect core to provide stub functions (__rust_alloc_error_handler is in alloc, but panic_handler resolution touches core's core_panic_2021 lang item)
Lang items — well-known items the compiler looks up by attribute (#[lang = "owned_box"], #[lang = "fn"], #[lang = "panic_info"]). These are how the compiler refers to types/functions defined in core and alloc. The complete list is in compiler/rustc_hir/src/lang_items.rs.

When you write 1 + 2, the compiler lowers it into a call to <i32 as core::ops::Add>::add. When you write for x in v, it lowers to IntoIterator::into_iter + a loop { match it.next() ... }. Without core, Rust syntax wouldn't have semantics.

Unicode tables

Things like char::is_alphabetic need Unicode property data. The data tables under library/core/src/unicode/ are generated by src/tools/unicode-table-generator/ from the Unicode Character Database. When Unicode releases a new version, regenerate.

SIMD and `core::simd`

The portable SIMD types (std::simd::*) live as a subtree at library/portable-simd/ and are re-exported from core::simd (still unstable). Architecture-specific intrinsics under core::arch::* come from library/stdarch/.

Testing

core's test suite lives in library/coretests/ — a separate crate that depends on core and uses the public API. It's structured this way because core itself can't easily host its own #[test]s (no allocator, no test runner) without leaking dependencies that would change core's code paths.

./x test library/core      # runs tests in coretests

Entry points for modification

A new method on a primitive (e.g., i32::checked_div) → likely in library/core/src/num/
A new iterator adapter → library/core/src/iter/adapters/
A new lang item → coordinate with the compiler team; touches rustc_hir::lang_items and a core definition
Async/Future plumbing → library/core/src/future/ and (often) the lang-team
Public API change → file an ACP, add #[unstable], then libs-api FCP