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
| Task | Recommended starting API | Guide |
|---|---|---|
| Print a value | console.println and console.printf |
Formatting and console output |
| Read a file | fs.read_file with platform.workspace() |
Filesystem |
| Get an environment variable | env.get with env.Workspace.new() |
Environment |
| Run a command | process.Command.new and output |
Processes |
| Build a string | text.Builder.new with a byte array |
Text |
| Decode or encode JSON | @derive(Json) and json.decode<T> |
JSON |
| Store values | fixed_vector.Vector.new with Option<T> slots |
Collections |
| Draw shapes, text, or images | graphics.canvas over a byte array |
Graphics |
| Decode or encode PNG, QOI, BMP or Netpbm files | image.info, image.decode and image.encode with caller buffers |
Images |
| Load, resize and save an image file | image_alloc.load, picture.resize and picture.save_auto |
Images |
| Draw smooth shapes, gradients, or TrueType text | canvas.aa_fill_circle, graphics.Gradient, truetype.Font.new |
Graphics |
| Open windows | window.App.new, app.open and win.canvas() |
Windows |
| Draw into a window with the GPU | window.Options.gpu, win.native_handle(), opengl.Context.create_for_window |
Windows |
| Render with the GPU through OpenGL | opengl.Context.create, opengl.Target.new and the gl commands |
OpenGL |
| Compute or render on any GPU | gpu.Device.open, device.encoder() and encoder.submit() |
GPU programming |
| Run a shader on the GPU (macOS) | metal.Device.system_default and new_library_with_source |
Metal |
| Call Vulkan directly | vk.open() and library.entry() from std/gpu/vulkan |
Vulkan |
| Call a function in a shared library | dylib.open and library.symbol |
Shared libraries |
| Read the current time | time/hosted.WallClock.new().wall_now() |
Time and clocks |
| Fetch a URL | http/hosted.Client.new and get |
HTTP, hosted HTTP/HTTPS |
| Serve a route | app.new().get(...).run(...) from std/web/app |
Web applications |
| React to MQTT messages or publish on a timer | app.new(id).on(...).every(...).run(url) from std/mqtt/app |
MQTT |
| Run an MQTT broker | broker.new().run(address) from std/mqtt/broker |
MQTT |
| Store data in an SQL database file | sqlite.Connection.open(path, workspace) and execute/select from std/db/sqlite |
SQLite databases |
| Map SQL rows to structs | @derive(Row), then T.decode_row(&row) and value.params() |
SQLite databases |
| Query a PostgreSQL server | postgres.connect(url, workspace) and execute/select from std/db/postgres |
PostgreSQL |
| Reuse database connections | db.Pool.new(&mut connections) and pool.get() |
PostgreSQL |
| Run Lua scripts or plugins inside a program | lua.Lua.new(), open_libs() and cx.do_string from std/script/lua |
Embedded scripting with Lua |
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.
| Storage choice | Use it when | What you manage |
|---|---|---|
| Borrowed view | Input or existing data already has an owner. | Keep that owner alive and avoid conflicting mutation. |
| Fixed array / caller-backed builder | You know a reasonable bound. | Capacity and the Result returned when it fills. |
| Hosted workspace | A hosted API offers a bounded convenience owner. | Workspace lifetime, documented limits, and whether outputs borrow it. |
| Arena / pool / owned container | Data needs separately owned storage or controlled growth. | An explicit allocator capability and its backing storage. |
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,
graphics, 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, OS entropy, crypto, TLS and QUIC backends and HTTP/web wrappers support x86-64
and AArch64 Linux GNU, macOS, and Windows x64 MSVC/GNU. They reject Linux
x32/musl 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, QUIC and
std/crypto/openssl also need OpenSSL 3.5 or newer. See platform adapters,
TLS, QUIC, and cryptography.
OS/C-library calls may allocate internally even when Dodo storage is fixed.
HTTP/1.1 clients, servers, streaming framing, web routing, and QUIC connections
and streams are implemented.
HTTP/2, HTTP/3, WebSockets, TOML serialization and chip support beyond
the RP2040, RP2350, ESP32-C6, and ATmega328P are remaining work. std/embedded/hal supplies typed
registers and portable device protocols, blocking and polling, including I2C
and SPI targets, pulse capture, timers at other rates with compare,
periodic, and capture channels, CAN, I2S, and DMA buffer transfers, with
in-memory fakes in std/embedded/hal/fake and the serial port protocols in
std/embedded/hal/serial; std/embedded/chip/rp2040 and
std/embedded/board/pico support the Raspberry Pi RP2040 and Pico, and
std/embedded/chip/rp2350 with std/embedded/board/pico2 and
std/embedded/board/pico2_w the RP2350, Pico 2, and Pico 2 W, including
their I2C and SPI buses, as master or target, and serial ports through the
shared controller drivers in std/embedded/peripheral and the pin and
controller ownership both chips share in std/embedded/chip/rp_pins, and
their PWM outputs and inputs, PWM slices as periodic timers, and ADC inputs
through std/embedded/chip/rp_pwm and std/embedded/chip/rp_adc, which also
runs the ADC by itself, sampling inputs round-robin into its FIFO for polled,
interrupt-driven, or DMA reads, their timer alarms as compare channels and
periodic timers, and the RP2350’s second timer, through
std/embedded/chip/rp_timer, edge capture on PIO through
std/embedded/chip/rp_capture, their random number generators, the RP2040’s
ring oscillator and the RP2350’s TRNG, through std/embedded/chip/rp_rng,
their PIO state machines, with programs assembled
at compile time, through std/embedded/chip/rp_pio, I2S audio on PIO
through std/embedded/chip/rp_i2s, a USB serial port on
the board’s own USB connector through std/embedded/chip/rp_usb, their DMA
channels through std/embedded/chip/rp_dma, which the SPI buses and serial
ports use for transfers that run in the background, their real-time clocks,
the RP2040’s RTC and the RP2350’s always-on timer, through
std/embedded/chip/rp_rtc, and their second core,
with the FIFOs, spinlocks, and RP2350 doorbells the cores share, through
std/embedded/chip/rp_multicore, their watchdog through
std/embedded/chip/rp_watchdog, and the free flash above the program
through std/embedded/chip/rp_flash. The clock gating, dormant state,
system-clock rates, and RP2350 power-down states both chips share are in
std/embedded/chip/rp_power. std/embedded/storage keeps
a power-cut-safe key-value store on that flash, or on any device with the
hal.Flash protocol, such as an external SPI NOR flash chip driven by
std/embedded/flash/spi_nor.
std/embedded/chip/esp32c6 with std/embedded/board/esp32c6_devkitc
supports the Espressif ESP32-C6 and ESP32-C6-DevKitC-1: GPIO through the
GPIO matrix, its interrupt matrix, I2C and SPI as master, polled, or target
and serial ports through std/embedded/peripheral/esp_i2c, esp_spi, and
esp_uart, SPI by DMA, serial ports by DMA through
std/embedded/peripheral/esp_uhci, CAN through std/embedded/peripheral/esp_twai,
I2S audio through std/embedded/chip/esp_i2s, PWM outputs and inputs
(std/embedded/chip/esp_capture), the calibrated ADC and temperature sensor
with continuous sampling (std/embedded/chip/esp_adc), the system timer’s
alarms, DMA copies through std/embedded/chip/esp_gdma, pulse trains through the remote control peripheral
(std/embedded/peripheral/esp_rmt) and WS2812 LEDs on it, such as the
board’s RGB LED, the random number
generator, the watchdog, the low-power timer as a real-time clock, the
flash above the program (std/embedded/chip/esp_rng,
std/embedded/chip/esp_watchdog, std/embedded/chip/esp_rtc,
std/embedded/chip/esp_flash), low power and hibernation
(std/embedded/chip/esp_power), the chip’s own USB
serial port through std/embedded/peripheral/esp_usb_serial, which dodo run also flashes through, and its low-power core, whose programs use
std/embedded/chip/esp32c6_lp and share LP SRAM through
std/embedded/chip/esp_lp_shared.
std/embedded/can/mcp2515 drives the MCP2515 CAN controller over any SPI bus.
std/embedded/cortex_m enables, pends, and prioritizes interrupts and runs
SysTick on any Cortex-M core. std/embedded/executor runs several firmware
tasks on a core, waking each on time or on an interrupt and sleeping
in between; tasks are hand-written or async fns.
std/embedded/sync shares values between interrupt handlers, tasks, and
cores through Mutex<T> statics. std/embedded/power is the low-power layer every chip implements:
sleep and deep sleep modes, clock gating, and a dormant state that pins or
a timeout end. std/embedded/wireless/cyw43 drives the Pico 2 W’s CYW43439 wireless chip
far enough for its LED; Wi-Fi and Bluetooth are not supported yet.
std/embedded/chip/atmega328p and std/embedded/board/arduino_uno support
the ATmega328P and Arduino Uno: pins, the serial port, I2C, SPI, PWM, the
ADC, the watchdog, and the EEPROM, flashed by dodo run through the board’s
bootloader. std/embedded/chip/attiny85 and std/embedded/board/digispark
do the same for the ATtiny85 and the Digispark, through its micronucleus
USB bootloader: pins, a transmit-only serial port, I2C and SPI on the USI,
PWM, the ADC, the watchdog, and the EEPROM.
std/embedded/rtc/ds3231 drives a DS3231 battery-backed clock chip on I2C
through the same real-time clock protocols as the chips’ own clocks.
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.
| Family and guide | Imports | Availability |
|---|---|---|
| Core utilities | core/mem, core/ptr, core/mmio, core/cpu, core/ascii, core/bytes, core/num, core/option, core/slice |
Portable. |
| Allocation and boxes | alloc/arena, alloc/arena_box, alloc/block, alloc/boxed, alloc/error, alloc/layout, alloc/pool, alloc/pool_box, alloc/shared_arena, alloc/shared_box |
Portable. |
| Binary bytes | std/arena_bytes, std/bytes, std/bytes_alloc, std/pool_bytes |
Portable. |
| Byte I/O | std/io, std/io_alloc |
Portable. |
| Compression | std/compress/deflate, std/compress/zlib, std/compress/gzip, std/compress/brotli, std/compress/io |
Portable; caller-supplied buffers. std/compress/brotli decompresses only. |
| Console I/O | std/console |
Hosted. |
| Formatting | std/fmt, std/fmt/errors, std/fmt_alloc |
Portable. |
| UTF-8 text | std/text, std/text_alloc, std/text_shared |
Portable. |
| JSON | std/encoding/json |
Portable; borrowed views and caller-supplied output storage. |
| Collections | std/collections, std/collections/deque, std/collections/fixed_deque, std/collections/fixed_map, std/collections/fixed_set, std/collections/fixed_vector, std/collections/hash_map, std/collections/hash_set, std/collections/heap, std/collections/ordered_map, std/collections/ordered_set, std/collections/shared_deque, std/collections/shared_hash_map, std/collections/shared_hash_set, std/collections/shared_heap, std/collections/shared_ordered_map, std/collections/shared_ordered_set, std/collections/shared_vector, std/collections/vector |
Portable. |
| Mathematics | std/math, std/math/trig |
Portable. |
| Hashing and checksums | std/checksum, std/hash |
Portable. |
| Graphics | std/graphics, std/graphics/fake, std/graphics/font, std/graphics/image, std/graphics/truetype; panels in std/embedded/display, std/embedded/display/st7789, std/embedded/display/ssd1306 |
Portable; caller-supplied pixel and file buffers. |
| Images | std/image, std/image/pixels, std/image/color, std/image/convert, std/image/sink, std/image/meta, std/image/ops, std/image/shared/binary, std/image/shared/scratch, std/image/shared/isobmff, std/image/ppm, std/image/qoi, std/image/bmp, std/image/png, std/image/jxl, std/image/jxl/encode; owned images and files in std/image_alloc |
Portable with caller-supplied pixel, scratch and file buffers; std/image_alloc adds an explicit allocator and hosted files. |
| Windows | std/window, std/window/x11, std/window/handle |
Hosted: X11 on Linux, AppKit on macOS, Win32 on Windows; the X11 protocol code and the native handle type are portable. |
| OpenGL | std/gpu/opengl, std/gpu/opengl/gl |
Hosted: EGL on Linux, CGL on macOS, WGL on Windows, loaded at run time; the generated binding is portable. |
| Metal | std/gpu/metal, std/gpu/metal/objc |
macOS only (Apple silicon and Intel); links Metal, QuartzCore and Foundation. |
| GPU programming | std/gpu, std/gpu/hal |
Hosted: Metal on macOS, Vulkan on Linux and Windows, OpenGL 4.5 where Vulkan is missing; nothing beyond Metal is linked. |
| Vulkan | std/gpu/vulkan |
Hosted; the Vulkan loader is opened at run time, nothing is linked. |
| Shared libraries | std/dylib |
Hosted: dlopen on Linux and macOS, LoadLibrary on Windows. |
| Time and clocks | std/time, std/time/clock, std/time/hosted, std/time/iso8601, std/time/timer |
Values/contracts portable; hosted clock explicit. |
| Native strings and errors | std/platform, std/platform/error |
Hosted. |
| Filesystem and lexical paths | std/fs, std/fs/path, std/fs/types, std/fs/unix, std/fs/windows_ext |
Paths/types portable; files hosted. |
| Environment | std/env |
Hosted. |
| Processes | std/process, std/process/alloc |
Hosted. |
| Signals | std/signal |
Hosted. |
| Threads | std/thread |
Hosted. |
| Synchronization | std/sync, std/sync/allocated, std/sync/atomic, std/sync/error |
Blocking/allocated hosted; atomic target-specific. |
| Networking and DNS | std/net, std/net/dns, std/net/operations |
Values/DNS/operations portable; native sockets hosted. |
| Cryptography | std/crypto, std/crypto/openssl, std/crypto/random |
Errors/secret helpers portable; OS entropy and OpenSSL hosted. |
| TLS | std/tls, std/tls/openssl, std/tls/stream |
Contracts/stream portable; OpenSSL hosted. |
| QUIC | std/quic, std/quic/openssl |
Error and state vocabulary portable; OpenSSL endpoints hosted. |
| HTTP, hosted HTTP/HTTPS | std/http, std/http/client, std/http/connection, std/http/hosted, std/http/https, std/http/server |
Protocol/polling portable; hosted/HTTPS explicit. |
| MQTT | std/mqtt, std/mqtt/app, std/mqtt/broker, std/mqtt/hosted |
Packets/topics/handlers/test deliveries portable; app, broker, and client hosted. |
| SQLite databases | std/db, std/db/sql, std/db/sqlite |
Vocabulary and interfaces portable; the SQLite driver is hosted (files) and written entirely in Dodo. |
| PostgreSQL | std/db/postgres, std/db/postgres/protocol |
Wire protocol portable; the client is hosted (sockets, OpenSSL for TLS and password hashes). |
| Web serving | std/web, std/web/application, std/web/app, std/web/hosted, std/web/https, std/web/reactor, std/web/response, std/web/server, std/web/static_files, std/web/stream, std/web/testing |
Routing/registration/composition portable; app/hosted/HTTPS/reactor/static files explicit. |
| Embedded scripting with Lua | std/script/lua |
Hosted: Linux, macOS, and Windows; io and os follow the target C library. |
| Hardware and embedded | std/embedded/hal, std/embedded/hal/serial, std/embedded/hal/fake, std/embedded/executor, std/embedded/sync, std/embedded/power, std/embedded/storage, std/embedded/flash/spi_nor, std/embedded/board, std/embedded/chip, std/embedded/peripheral/designware_i2c, std/embedded/peripheral/pl022, std/embedded/peripheral/pl011, std/embedded/peripheral/esp_i2c, std/embedded/peripheral/esp_spi, std/embedded/peripheral/esp_uart, std/embedded/peripheral/esp_usb_serial, std/embedded/peripheral/esp_twai, std/embedded/wireless/cyw43, std/embedded/can/mcp2515, std/embedded/rtc/ds3231, std/embedded/cortex_m |
std/embedded/hal, std/embedded/executor, std/embedded/sync, and std/embedded/power are portable, with interrupt masking on bare-metal Cortex-M and RISC-V. std/embedded/cortex_m (interrupt controller, SysTick, barriers) runs only on Cortex-M. std/embedded/board and std/embedded/chip resolve to the firmware build’s board and chip packages, such as std/embedded/board/pico2 and std/embedded/chip/rp2350, or std/embedded/board/esp32c6_devkitc and std/embedded/chip/esp32c6. |
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.
| Imports | Role and entry point |
|---|---|
std/crypto/openssl/posix |
Native OpenSSL libcrypto boundary; use cryptography. |
std/crypto/openssl/windows |
Native OpenSSL libcrypto boundary; use cryptography. |
std/crypto/posix |
Native OS entropy boundary; use random bytes. |
std/crypto/windows |
Native OS entropy boundary; use random bytes. |
std/dylib/posix |
Native library loading boundary; use shared libraries. |
std/dylib/windows |
Native library loading boundary; use shared libraries. |
std/env/posix |
Target-specific provider machinery; use the corresponding hosted facade. |
std/env/windows |
Target-specific provider machinery; use the corresponding hosted facade. |
std/float_decimal |
Internal decimal conversion; use formatting or text parsing. |
std/fs/posix |
Target-specific provider machinery; use the corresponding hosted facade. |
std/fs/windows |
Target-specific provider machinery; use the corresponding hosted facade. |
std/http/hosting |
Shared hosted driving/error support; use HTTP or web serving. Import this only when naming its shared Error type or building a provider. |
std/net/posix |
Selected socket adapter; use networking. |
std/net/windows |
Selected socket adapter; use networking. |
std/platform/posix |
Target-specific provider machinery; use the corresponding hosted facade. |
std/platform/windows |
Target-specific provider machinery; use the corresponding hosted facade. |
std/process/posix |
Target-specific provider machinery; use the corresponding hosted facade. |
std/process/windows |
Target-specific provider machinery; use the corresponding hosted facade. |
std/signal/posix |
Native signal boundary; use signals. |
std/signal/windows |
Native signal boundary; use signals. |
std/sync/posix |
Target-specific provider machinery; use the corresponding hosted facade. |
std/sync/windows |
Target-specific provider machinery; use the corresponding hosted facade. |
std/thread/posix |
Target-specific provider machinery; use the corresponding hosted facade. |
std/thread/native |
Target-specific provider machinery; use the corresponding hosted facade. |
std/thread/windows |
Target-specific provider machinery; use the corresponding hosted facade. |
std/time/posix |
Native clock boundary; use hosted clocks. |
std/time/windows |
Native clock boundary; use hosted clocks. |
std/tls/posix |
Native OpenSSL boundary; use TLS. |
std/tls/windows |
Native OpenSSL boundary; use TLS. |
std/quic/posix |
Native OpenSSL QUIC boundary; use QUIC. |
std/quic/windows |
Native OpenSSL QUIC boundary; use QUIC. |
std/web/posix |
Native rooted-file boundary; use static files. |
std/web/windows |
Native rooted-file boundary; use static files. |
std/window/linux |
X11 window adapter over the protocol in std/window/x11; use windows. |
std/window/macos |
Native Cocoa window boundary; use windows. |
std/window/windows |
Native Win32 window boundary; use windows. |
std/window/system |
The C-runtime adapter the macOS and Windows boundaries share; use windows. |
std/window/raw |
Error and event records exchanged with the adapters; use windows. |
std/window/heap |
C-heap pixel buffers and window tables shared by std/window and its adapters; use windows. |
std/gpu/opengl/linux |
EGL context adapter; use OpenGL. |
std/gpu/opengl/macos |
CGL context adapter; use OpenGL. |
std/gpu/opengl/windows |
WGL context adapter; use OpenGL. |
std/gpu/opengl/common |
Error type and helpers the adapters share; use OpenGL. |
std/script/posix |
Lua host boundary on Linux and macOS (C library streams, processes, time, locale); use Lua. |
std/script/windows |
Lua host boundary on Windows; use Lua. |
std/gpu/hal/vulkan |
std/gpu’s Vulkan backend; use GPU programming. |
std/gpu/hal/vulkan/memory |
The Vulkan backend’s memory sub-allocator; use GPU programming. |
std/gpu/hal/opengl |
std/gpu’s OpenGL backend; use GPU programming. |
std/gpu/hal/macos |
std/gpu’s Metal backend, its native one on macOS; use GPU programming. |
std/gpu/hal/linux |
std/gpu’s native backend on Linux, which has none; use GPU programming. |
std/gpu/hal/windows |
std/gpu’s native backend on Windows, which has none yet; use GPU programming. |
std/gpu/hal/unavailable |
The backend that never opens, behind the Linux and Windows native imports; use GPU programming. |
Virtual imports std/platform/native, std/fs/native, std/env/native,
std/process/native, std/signal/native, std/thread/native, std/sync/native, std/net/native,
std/time/native, std/tls/native, std/quic/native, std/crypto/native,
std/crypto/openssl/native, std/web/native, std/window/native,
std/gpu/opengl/native, std/gpu/hal/native and std/script/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, core/mmio and core/cpu 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.
| Topic | Guide |
|---|---|
| Checked sizes, byte operations, moving values, and opaque storage | Core utilities |
| Layouts, arenas, pools, boxes, and shared allocator capabilities | Allocation |
| Cursors and growing byte buffers | Binary bytes |
| Reader/writer contracts, bounded adapters, and allocated I/O | Byte I/O |
| Formatting numbers, strings, and custom values | Formatting |
| UTF-8 validation, borrowed text, builders, and numeric parsing | Text |
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_windows.py stdlib
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, andwrite_file. - Environment and arguments:
env.getandArguments.capture. - Processes:
CommandStorage,Command.arg, and boundedCommand.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.