Choose a library

Dodo’s standard library supplies reusable packages for data, storage, operating system services, and network applications. It is embedded in the compiler: import "std/text" works without downloading or installing another dependency.

Start with a task below and follow its guide. For the exact signature of any public type, field, function, or method, use the API reference and complete package directory. The generated reference covers every bundled source package; compiler intrinsics and virtual imports are documented separately because they are implemented by the compiler.

These guides follow the source checkout. If an older compiler reports an unknown package or method, compare dodo --version with the docs revision and build the matching source if needed.

Learn the library in stages

After the language basics, begin with console, formatting, and text. Then learn fixed-capacity collections and byte I/O. These packages make the central ideas concrete: storage has an owner, views borrow it, and operations report errors through Results.

Use allocation when a fixed capacity no longer fits your task. Add filesystem, processes, or networking when a program needs external services. Raw memory, custom allocators, provider internals, and concurrency are advanced topics; they are not prerequisites for using the safe entry APIs.

Choose a task

Use a fresh directory for each copied example and run the commands there. A marked dodo test example also runs through dodo test docs --doc in this repository. Peer/file examples use the local setup shown in their guides; none requires a public Internet service.

Imports, storage, and failures

Import names are explicit

Import only the packages you use. The last path component becomes its name: import "std/text" exposes text.Builder. Alias duplicate names explicitly, for example import "std/http/hosted" as client. Imports are not re-exports; application code must import the types and helpers it names. See packages.

The top-level families describe dependencies, not an automatic module hierarchy: core provides low-level portable operations, alloc supplies explicit allocation capabilities, and std contains higher-level services. Importing std/collections does not also import std/collections/fixed_vector.

Choose where data lives

Start with fixed arrays and the recommended workspace/constructor in each guide. They keep capacity visible and need no global heap. Choose shared-arena owned containers when growth or several independent owners are needed; use raw/generic allocator constructors only when implementing a custom allocator. The library never silently selects an allocator on exhaustion.

Owning a value and allocating memory are different ideas. A struct can own an inline array without using an allocator, and a slice can borrow allocated memory without owning it. The ownership guide explains moves and borrows.

Decide how to handle failure

Results must be handled. Examples use match at main and propagate with ? inside helpers. A nonzero exit status denotes failure; the text beside each example explains the codes. For user-facing diagnostics use console.stderr().println with a formatted error; std/fmt/errors supplies optional adapters for enum errors. Check I/O prefix counts before retrying. Patterns and Results explains the syntax.

Read each guide’s failure behavior as well as its error type. A full container may reject and destroy the supplied value, a writer may have transferred a prefix before failing, and a returned view may borrow a reusable workspace. Those details determine whether retrying or reusing storage is valid.

Portable and hosted functionality

Portable core, allocation, bytes, text, JSON, collections, math, hashes, time values, DNS/TLS contracts, HTTP/1.1 protocol engines and web routing require no OS, libc, global allocator, scheduler or garbage collector. Portable fixture checks emit wasm32-unknown-unknown and thumbv6m-none-eabi objects at O0 and O3. This is code-generation evidence, not tested board startup or hardware execution. Freestanding links supply startup, memory helpers and any soft-float support.

Hosted console, filesystem, environment, processes, clocks, threads, synchronization, sockets, TLS backends and HTTP/web wrappers support x86-64 Linux GNU and Windows x64 MSVC/GNU. They reject Linux x32/musl, AArch64 Linux, macOS and other unsupported ABIs. Atomic operations have a separate x86-64/AArch64 target contract. Hosted linking needs a target C toolchain and headers; OpenSSL-backed TLS also needs OpenSSL 3.5 or newer. See platform adapters and TLS. OS/C-library calls may allocate internally even when Dodo storage is fixed.

HTTP/1.1 clients, servers, streaming framing, and web routing are implemented. HTTP/2, HTTP/3/QUIC, WebSockets, TOML serialization and general peripheral drivers are remaining work. MMIO primitives alone do not configure a device. Compiler limits and container element restrictions remain relevant: check them when using references or Results as stored elements.

Packages

Every application-facing family has a guide. Child packages are separate imports; importing a parent does not import all its children.

The API package directory expands this family inventory into individual modules and links every public declaration back to its source.

Implementation and adapter packages

Prefer the application APIs above. The following imports exist to implement or select providers; they are not additional recommended starting paths.

Virtual imports std/platform/native, std/fs/native, std/env/native, std/process/native, std/thread/native, std/sync/native, std/net/native, std/time/native, std/tls/native, and std/web/native select compatible providers. std/platform/native exposes advanced native values; std/net/native is also the public socket entry point. Explicit linux/windows imports are for matching-target integrations. runtime.c files are embedded implementation boundaries, not Dodo imports.

alloc/error and alloc/layout are public supporting types. alloc/block and the unsafe generic constructors in alloc/boxed, std/bytes_alloc, and owned collection modules are allocator-author building blocks; use the linked safe concrete constructors first. core/mem, core/ptr and core/mmio are compiler intrinsics, not source packages.

Storage and data guides

The package inventory above links to complete guides. These topic links help when you know the operation you need but not the package name.

Dependency boundaries

Networking preserves three independent boundaries: portable addresses, DNS/HTTP protocol engines and routing; selected transport, TLS, time and execution providers; and clients/servers that compose them. See networking, TLS, HTTP, and web applications. Importing std/http or std/web requires no sockets, TLS, filesystem, allocator or scheduler.

flowchart BT
  core[Core byte and pointer primitives]
  values[Slice algorithms, math, hash, time values] --> core
  text[Binary bytes and UTF-8 text] --> core
  io[Byte I/O contracts and memory adapters] --> core
  fmt[Formatting] --> io
  fmt --> text
  time_text[Time parsing and formatting] --> values
  time_text --> text
  time_text --> fmt
  fixed[Caller-backed containers] --> core
  alloc[Explicit allocation capabilities] --> core
  owned[Owned containers and boxes] --> alloc
  owned --> values
  owned_text[Owned bytes, text, I/O and formatting] --> alloc
  owned_text --> text
  owned_text --> io
  owned_text --> fmt
  clocks[Clock and timer contracts and fakes] --> values
  adapters[Application OS, entropy, timer and timezone adapters] --> clocks

No portable package requests entropy, obtains the current time, waits, starts a runtime, or installs a global allocator. Hashing never imports collections; time values never import clocks. Generic customization is monomorphized ordinary method dispatch. The linked module guides and the collections, math, hash, and time pages specify storage, complexity, ordering, invalidation, and numerical contracts.

Verification

cargo test --locked --all-targets includes native execution at -O0 and -O3, allocation failure and reuse, drop order, and rejection of invalid lifetimes, unsafe calls, aliases, and Result handling. Portable fixtures also emit WebAssembly and Cortex-M0 objects; object generation does not test board startup or actual hardware execution.

Windows tests cross-compile the same core/alloc/std fixtures to x64 PE executables and run them in Wine at both optimization levels:

cargo build --locked --bin dodo
python3 scripts/test_stdlib_windows.py
python3 scripts/test_portable_stdlib.py

The script requires Clang, lld-link, Wine, and a MinGW libkernel32.a import library (or --kernel32 PATH). Fedora also needs the matching wine-common data package; Wine’s first-run setup needs its metadata files. The script uses a temporary Wine prefix, forwards each fixture’s exit status through a minimal Windows startup, and supplies compiler memory helpers and LLVM’s stack probe without linking a Windows C runtime or allocator. The probe is exercised by the large-allocation failure fixture. This tests Dodo-generated Windows programs, not a Windows build of the Rust compiler. --wine PATH --wineserver PATH selects a matching local Wine installation, including an unpacked installation with its complete data directory; no system installation change is required. Both scripts accept --fixture for a focused run and --report PATH for machine-readable validation records. The portable object runner checks all fixtures at O0 and O3 for WebAssembly and Cortex-M0.

Hosted conveniences

Hosted applications can use UTF-8 strings and bounded reusable workspace owners:

• Filesystem: File.open_utf8, read_file, and write_file.
• Environment and arguments: env.get and Arguments.capture.
• Processes: CommandStorage, Command.arg, and bounded Command.output.
• Native clocks: hosted monotonic and wall clocks.
• Console: borrowed standard streams, printing, and bounded line input.

Platform storage and complete examples document capacities, retained output, defaults, timeout scope, and target differences. Portable packages remain usable independently; native byte and UTF-16 APIs remain available.