Standard library

Active contributors: Filipp Zhinkin, Ilya Gorbunov, Sergej Jaskiewicz

libraries/stdlib/ is the Kotlin standard library: collection helpers, sequences, ranges, text and number utilities, time, IO, and the contract of the language built-ins (Int, String, List, ...). It is multiplatform from the bottom up: each target has its own implementation that satisfies the common API.

Purpose

Define the API every Kotlin program can rely on, and provide an implementation for each supported target. The stdlib is the most-used Kotlin code in existence — its API stability is paramount.

Directory layout

libraries/stdlib/
├── common/                Common API: expect declarations + cross-platform implementations
├── common-js-wasmjs/      Code shared between JS and Wasm/JS
├── common-non-jvm/        Code shared by non-JVM targets
├── jvm/                   JVM-specific actuals + JVM-only APIs (java.io, java.util, ...)
├── js/                    JavaScript actuals + JS-only APIs (dynamic, external, ...)
├── wasm/                  WebAssembly actuals
├── native-wasm/           Native + Wasm shared bits
├── jdk7/                  java.nio.file etc. (JDK 7+ APIs)
├── jdk8/                  Streams, java.util.function (JDK 8+ APIs)
├── jvm-minimal-for-test/  A minimal JVM stdlib for compiler self-testing
├── js-ir-minimal-for-test/ Minimal JS IR stdlib for compiler self-testing
├── jklib-for-test/        Test-only jklib variant
├── samples/               Code samples embedded in KDoc
├── unsigned/              UInt/ULong/UByte/UShort sources (compile separately)
├── src/                   A few cross-cutting pieces (rare)
└── test/                  Stdlib tests

Key abstractions

Type	Where	Role
kotlin.collections.List, Map, Set	libraries/stdlib/common/.../collections	Collection abstractions. JVM actuals map to java.util.List etc.
kotlin.sequences.Sequence	libraries/stdlib/common/.../sequences	Lazy sequences and operators.
kotlin.ranges.IntRange, LongRange, ...	libraries/stdlib/common/.../ranges	Range and progression types.
kotlin.text.StringBuilder, Regex	libraries/stdlib/common/.../text	Text utilities.
kotlin.time.Duration, TimeSource, Instant	libraries/stdlib/common/.../time	Time types.
kotlin.io	libraries/stdlib/common/.../io (+ jvm/)	IO; mostly JVM but some Path and KIO bits in common.
Result, Lazy, Pair, Triple, Comparator	libraries/stdlib/common/.../*	Foundational built-ins.
UInt, ULong, UByte, UShort	libraries/stdlib/unsigned/	Unsigned integer types (compiled separately for inline class compatibility).

Multiplatform via expect/actual

The stdlib API is declared once in common/ using expect:

// libraries/stdlib/common/.../text/regex/Regex.kt
public expect class Regex {
    public fun matches(input: CharSequence): Boolean
    // ...
}

Per-target actual declarations live in jvm/, js/, wasm/, and the Native sources (which live in kotlin-native/runtime/src/main/kotlin/). The compiler matches expect to actual at compile time.

Generation

A non-trivial fraction of the stdlib is generated to avoid duplicating boilerplate across primitive types:

• libraries/tools/kotlin-stdlib-gen/ is the generator.
• It expands templates over Int, Long, Float, Double, Char, ... into per-type implementations.
• The output files are committed.

Edit the template, run the generator, commit both. Don't edit the generated files directly.

Per-target peculiarities

Target	Key files	Notes
JVM	libraries/stdlib/jvm/	Most collection types delegate to java.util.*. kotlin.io exposes java.io.File extensions. JDK7/JDK8 sub-modules add APIs gated on the JDK level.
JS	libraries/stdlib/js/	Collections are pure-Kotlin implementations (no java.util). dynamic and external types are exposed here.
Wasm	libraries/stdlib/wasm/ and libraries/stdlib/native-wasm/	Mostly shares with JS for Wasm/JS; Wasm/WASI has additional system-interface support.
Native	Lives in kotlin-native/runtime/src/main/kotlin/	Uses Kotlin/Native intrinsics for runtime primitives. The Native standard library is split between this repo and kotlin-native/runtime.

API stability

Stdlib follows Kotlin's binary compatibility guarantees: stable APIs cannot be changed in a breaking way. Experimental APIs are marked @OptIn (e.g., @ExperimentalTime, @ExperimentalUnsignedTypes) and require an opt-in to use.

libraries/tools/abi-validation/ and libraries/tools/binary-compatibility-validator/ enforce this with checked-in API dumps. Any change touching stdlib's public surface requires updating the corresponding .api (and klib ABI) dump in the same commit.

Documentation

KDoc on stdlib symbols is the main API documentation. Code samples are kept in libraries/stdlib/samples/ and embedded into KDoc with @sample references; the doc-site rendering pulls them in. The doc site itself is generated via libraries/tools/kotlin-stdlib-docs/ (modern) and libraries/tools/kotlin-stdlib-docs-legacy/ (older Dokka-based).

Tests

libraries/stdlib/test/ houses stdlib tests, which run on every target. They use kotlin-test for assertions. Per-target Gradle tasks include coreLibsTest for the lot, plus per-target tasks like :kotlin-stdlib:jvmTest.

Integration points

• Consumed by: every Kotlin program. Distributed as kotlin-stdlib, kotlin-stdlib-jdk7, kotlin-stdlib-jdk8, kotlin-stdlib-js, kotlin-stdlib-wasm-js, kotlin-stdlib-wasm-wasi, plus klib variants.
• Built with: an earlier (bootstrap) Kotlin compiler, since this code defines the language built-ins themselves.
• Tested by: target-specific runners, plus the compiler test suite uses stdlib code as test inputs.

Where to start

Common API → libraries/stdlib/common/. JVM-specific → libraries/stdlib/jvm/. JS → libraries/stdlib/js/. Wasm → libraries/stdlib/wasm/. For a new function: add it to common/ first with expect, then actual for every target that needs a custom implementation.

When adding APIs that affect klib ABI, run ./gradlew :kotlin-stdlib:apiCheck (or rely on CI's failure to remind you) and update the dump file.