Library Development Guide

This guide covers development of Rust’s standard library ecosystem, including core, alloc, std, and related libraries.

Library Structure

The Rust standard library is organized into several layers:

core - The Foundation

The core library is the dependency-free foundation of Rust.Location: library/core/Features:

No dependencies (not even libc)
No heap allocation
No I/O
Platform-agnostic
Used in #![no_std] environments

alloc - Memory Management

The alloc library provides heap allocation primitives.Location: library/alloc/Features:

Requires a global allocator
Collections: Vec, String, Box, etc.
No I/O or OS dependencies

std - The Standard Library

The standard library builds on core and alloc.Location: library/std/Features:

OS interaction
I/O operations
Threading
File system
Networking

Library Directory Layout

library/
├── core/                  # Core library (no_std)
│   ├── src/
│   │   ├── lib.rs
│   │   ├── ptr/          # Pointer utilities
│   │   ├── slice/        # Slice operations
│   │   ├── str/          # String slice operations
│   │   └── ...
│   └── Cargo.toml
├── alloc/                 # Allocation and collections
│   ├── src/
│   │   ├── lib.rs
│   │   ├── vec/          # Vec implementation
│   │   ├── string.rs     # String type
│   │   ├── boxed.rs      # Box type
│   │   └── collections/  # HashMap, BTreeMap, etc.
│   └── Cargo.toml
├── std/                   # Standard library
│   ├── src/
│   │   ├── lib.rs
│   │   ├── fs/           # File system
│   │   ├── io/           # I/O traits and types
│   │   ├── net/          # Networking
│   │   ├── thread/       # Threading
│   │   └── ...
│   └── Cargo.toml
├── test/                  # Test framework
├── proc_macro/            # Procedural macros
├── panic_abort/           # Panic abort handler
├── panic_unwind/          # Panic unwinding
├── unwind/                # Stack unwinding
└── backtrace/             # Backtrace support

Setting Up for Library Development

Configure for library development

Create or modify config.toml:

profile = "library"

[llvm]
download-ci-llvm = true

[rust]
# Download pre-built compiler if working only on library
download-rustc = "if-unchanged"

# Build library with debug info
debuginfo-level-std = 1

Build the library

# Build just the standard library
./x.py build library/std

# Build core library
./x.py build library/core

# Build alloc library
./x.py build library/alloc

Test your changes

# Test standard library
./x.py test library/std

# Test core library
./x.py test library/core

# Test specific module
./x.py test library/std --test-args vec

Working with Core Library

Core Library Constraints

The core library has special restrictions:

The core library cannot:

Use heap allocation
Perform I/O operations
Access the file system
Use OS-specific features
Depend on external crates (except compiler intrinsics)

Example: Adding to Core

Safe API
Unsafe API
Tests

// library/core/src/slice/mod.rs

impl<T> [T] {
    /// Returns the first element of the slice.
    #[stable(feature = "slice_first", since = "1.0.0")]
    pub const fn first(&self) -> Option<&T> {
        if let [first, ..] = self {
            Some(first)
        } else {
            None
        }
    }
}

// library/core/src/ptr/mod.rs

/// Reads the value from `src` without moving it.
#[inline]
#[stable(feature = "rust1", since = "1.0.0")]
pub const unsafe fn read<T>(src: *const T) -> T {
    // SAFETY: the caller must guarantee that `src` is valid
    unsafe {
        let mut tmp = MaybeUninit::<T>::uninit();
        copy_nonoverlapping(src, tmp.as_mut_ptr(), 1);
        tmp.assume_init()
    }
}

// library/core/tests/slice.rs

#[test]
fn test_first() {
    let v: &[i32] = &[1, 2, 3];
    assert_eq!(v.first(), Some(&1));
    
    let empty: &[i32] = &[];
    assert_eq!(empty.first(), None);
}

Working with Alloc Library

Memory Allocation Primitives

The alloc library provides heap-allocated types:

// library/alloc/src/vec/mod.rs

impl<T> Vec<T> {
    pub fn push(&mut self, value: T) {
        // Check if we need to grow the buffer
        if self.len == self.buf.capacity() {
            self.grow_amortized(self.len + 1);
        }
        unsafe {
            let end = self.as_mut_ptr().add(self.len);
            ptr::write(end, value);
            self.len += 1;
        }
    }
}

Working with Std Library

Platform-Specific Code

The std library contains platform-specific implementations:

Unix
Windows
Common Interface

// library/std/src/sys/pal/unix/fs.rs

#[cfg(unix)]
pub fn read_dir(path: &Path) -> io::Result<ReadDir> {
    let path = cstr(path)?;
    unsafe {
        let ptr = libc::opendir(path.as_ptr());
        if ptr.is_null() {
            Err(io::Error::last_os_error())
        } else {
            Ok(ReadDir { dirp: ptr, root: path })
        }
    }
}

// library/std/src/sys/pal/windows/fs.rs

#[cfg(windows)]
pub fn read_dir(path: &Path) -> io::Result<ReadDir> {
    let path = to_u16s(path)?;
    unsafe {
        let mut find_data = c::WIN32_FIND_DATAW::default();
        let handle = c::FindFirstFileW(path.as_ptr(), &mut find_data);
        if handle == c::INVALID_HANDLE_VALUE {
            Err(io::Error::last_os_error())
        } else {
            Ok(ReadDir { handle, first: Some(find_data) })
        }
    }
}

// library/std/src/fs.rs

pub fn read_dir<P: AsRef<Path>>(path: P) -> io::Result<ReadDir> {
    // Delegates to platform-specific implementation
    sys::fs::read_dir(path.as_ref())
}

Library Development Workflow

Make your changes

Edit the appropriate library file in library/core/, library/alloc/, or library/std/.

Add tests

Doc Tests
Unit Tests

/// Returns the first element.
///
/// # Examples
///
/// ```
/// let v = vec![1, 2, 3];
/// assert_eq!(v.first(), Some(&1));
/// ```
pub fn first(&self) -> Option<&T> {
    // implementation
}

// In library/core/tests/ or library/std/tests/

#[test]
fn test_vec_push() {
    let mut v = Vec::new();
    v.push(1);
    v.push(2);
    assert_eq!(v, [1, 2]);
}

Build and test

# Build the library
./x.py build library/std

# Run library tests
./x.py test library/std

# Run doc tests
./x.py test library/std --doc

# Test specific module
./x.py test library/std --test-args vec

Check all platforms

# Test on different platforms
./x.py test library/std --target x86_64-pc-windows-gnu
./x.py test library/std --target aarch64-apple-darwin

Library Features

Feature Flags in Std

The standard library uses feature flags for conditional compilation:

// library/std/Cargo.toml
[features]
backtrace = ["addr2line", "object", "miniz_oxide"]
panic-unwind = ["dep:panic_unwind"]
compiler-builtins-mem = ["alloc/compiler-builtins-mem"]

Usage in code:

#[cfg(feature = "backtrace")]
pub mod backtrace;

#[cfg(not(feature = "backtrace"))]
pub mod backtrace {
    // Stub implementation
}

Stability Attributes

All public APIs must have stability attributes:

#[stable(feature = "rust1", since = "1.0.0")]
pub fn is_empty(&self) -> bool {
    self.len() == 0
}

Testing Libraries

Test Organization

Library Tests
Doc Tests
Integration Tests

library/
├── core/tests/         # Core library tests
│   ├── slice.rs
│   ├── iter.rs
│   └── ...
├── alloc/tests/        # Alloc library tests
│   ├── vec.rs
│   ├── string.rs
│   └── ...
└── std/tests/          # Std library tests
    ├── fs.rs
    ├── thread.rs
    └── ...

Embedded in the library source:

/// # Examples
///
/// ```
/// use std::collections::HashMap;
///
/// let mut map = HashMap::new();
/// map.insert(1, "a");
/// assert_eq!(map.get(&1), Some(&"a"));
/// ```

# Located in tests/ui, tests/run-make, etc.
./x.py test tests/ui --test-args library

Running Library Tests

# All standard library tests
./x.py test library/std

# Specific test file
./x.py test library/std --test-args vec

# With output
./x.py test library/std -- --nocapture

Cross-Platform Development

Platform Abstraction Layers

The std library uses a Platform Abstraction Layer (PAL):

library/std/src/sys/pal/
├── unix/           # Unix-like systems
│   ├── linux/     # Linux-specific
│   ├── macos/     # macOS-specific
│   └── ...
├── windows/        # Windows
├── wasm/          # WebAssembly
└── unsupported/   # Unsupported platforms

Conditional Compilation

#[cfg(target_os = "linux")]
fn platform_specific() {
    // Linux implementation
}

#[cfg(target_os = "windows")]
fn platform_specific() {
    // Windows implementation
}

#[cfg(target_family = "unix")]
fn unix_specific() {
    // All Unix-like systems
}

Performance Considerations

Use #[inline]

#[inline]
pub fn len(&self) -> usize {
    self.len
}

Small functions benefit from inlining

Avoid Allocations

Use iterators and stack allocation when possible

Benchmarking

./x.py bench library/std

Size Optimization

Use optimize_for_size feature for embedded targets

Common Tasks

Adding a new method to Vec

Edit library/alloc/src/vec/mod.rs
Add implementation with stability attributes
Add doc tests with examples
Add unit tests in library/alloc/tests/vec.rs
Run ./x.py test library/alloc

Fixing a bug in std::fs

Edit library/std/src/fs.rs or platform-specific file
Add regression test
Test on multiple platforms
Run ./x.py test library/std --test-args fs

Optimizing core::slice

Edit library/core/src/slice/mod.rs
Add benchmarks if needed
Ensure no unsafe code bugs
Test thoroughly with Miri: ./x.py test library/core --stage 0

Resources

Std Dev Guide

Standard library development guide

Library Team

Chat with the library team on Zulip

API Guidelines

Rust API design guidelines

Libs Tracking

Library issues on GitHub

Next Steps

Compiler Development

Learn about compiler development

Debugging

Debug library issues

Profiling

Profile library performance

Contributing Guide

Development

Library Development Guide

Library Structure

Library Directory Layout

Setting Up for Library Development

Working with Core Library

Core Library Constraints

Example: Adding to Core

Working with Alloc Library

Memory Allocation Primitives

Working with Std Library

Platform-Specific Code

Library Development Workflow

Library Features

Feature Flags in Std

Stability Attributes

Testing Libraries

Test Organization

Running Library Tests

Cross-Platform Development

Platform Abstraction Layers

Conditional Compilation

Performance Considerations

Use #[inline]

Avoid Allocations

Benchmarking

Size Optimization

Common Tasks

Resources

Std Dev Guide

Library Team

API Guidelines

Libs Tracking

Next Steps

Compiler Development

Debugging

Profiling

Build docs developers (and LLMs) love

Contributing Guide

Development

Documentation Index

​Library Structure

​Library Directory Layout

​Setting Up for Library Development

​Working with Core Library

​Core Library Constraints

​Example: Adding to Core

​Working with Alloc Library

​Memory Allocation Primitives

​Working with Std Library

​Platform-Specific Code

​Library Development Workflow

​Library Features

​Feature Flags in Std

​Stability Attributes

​Testing Libraries

​Test Organization

​Running Library Tests

​Cross-Platform Development

​Platform Abstraction Layers

​Conditional Compilation

​Performance Considerations

Use #[inline]

Avoid Allocations

Benchmarking

Size Optimization

​Common Tasks

​Resources

Std Dev Guide

Library Team

API Guidelines

Libs Tracking

​Next Steps

Compiler Development

Debugging

Profiling

Build docs developers (and LLMs) love

Library Structure

Library Directory Layout

Setting Up for Library Development

Working with Core Library

Core Library Constraints

Example: Adding to Core

Working with Alloc Library

Memory Allocation Primitives

Working with Std Library

Platform-Specific Code

Library Development Workflow

Library Features

Feature Flags in Std

Stability Attributes

Testing Libraries

Test Organization

Running Library Tests

Cross-Platform Development

Platform Abstraction Layers

Conditional Compilation

Performance Considerations

Common Tasks

Resources

Next Steps