Ocean documentation
Learn how to install Ocean, write and organize programs, and use the compiler and standard library. The language guide assumes you know programming basics, but does not require experience with any particular language.
NEW TO OCEAN?Install Ocean and run a program. ↗
Start with the source checkout and compiler setup, then write and run a complete example.
Language guide
Variables & basic types↗
Declare values, work with numbers, and make conversions explicit.
Control flow↗
Conditions, loops, and switches with familiar, explicit structure.
Functions↗
Typed parameters, multiple results, variadic calls, and predictable value semantics.
Packages & imports↗
Organize files, import shared code, and understand visibility and method ownership.
Strings↗
Immutable byte strings, explicit formatting, and independent copies.
Arrays, maps & buffers↗
Choose the collection that fits its lifetime, size, and access requirements.
Structs & named types↗
Model data with value types, methods, and deliberate type identities.
Enums & matching↗
Construct tagged enum values, extract immutable payloads, and match variants.
Generics & interfaces↗
Reusable types and functions with explicit specialization and type constraints.
Memory & pointers↗
Automatic cleanup for owned values, explicit lifetimes for heap pointers.
Errors↗
Schedule deferred cleanup, recover panics, and forward failures to callers.
C interop↗
Call native libraries with an explicit ABI and work with C strings and pointers.
Inline assembly↗
Write architecture-specific assembly with optional platform selection.
Tutorials
Tooling
Packages & modules↗
Organize source files and share code across local and external packages.
Compiler & CLI↗
Build native executables, inspect LLVM, and understand the build cache.
Unit tests↗
Run package tests with testing.T, private or external test packages, tang reports, JSON events, and saved results.
Editor integration↗
Connect an LSP-capable editor to the Ocean compiler.
Standard library
io↗
Print and format values, parse numeric strings into Result values, and scan files or standard input.
encoding/json↗
Encode JSON, decode dynamic objects and arrays, and preserve exact number text.
net/http↗
HTTP/1.1 and verified HTTPS, overall deadlines, cancellation, and native/Wasm transport boundaries.
os/exec↗
Run executables directly, capture output, and configure the working directory and environment.
os↗
Read process arguments, exit the process, access standard streams, and work with native files.
term↗
Query terminal dimensions, detect terminal streams, read passwords without echo, and enter or restore raw mode.
term/tui↗
Build terminal applications with a Model interface, asynchronous commands, keyboard events, and terminal rendering.
math↗
Compute binary64 powers, roots, trigonometry, logarithms, rounding, and IEEE helpers.
mem↗
Copy raw bytes between memory regions, including overlapping regions.
time↗
Sleep the calling thread using nanosecond durations and integer time units.
threads↗
Start native threads from functions, await completion, park and wake threads, and terminate individual threads.
sync↗
Protect shared state with mutexes and wait for groups of native threads to finish.
reflect↗
Inspect struct and enum payload snapshots without depending on their native memory layout.
Contribute
Source code↗
Find the repositories for the Ocean compiler, standard library, and documentation.
Building & compiler architecture↗
Build a development compiler, find each compilation stage, and choose the right tests for a change.
Standard library repository↗
Understand the ocean-src layout, its compiler integration, and how to verify library changes.
Contribute to the docs website↗
Clone the website, run it locally, and add documentation pages through the shared content model.
Based on the current Ocean compiler README and the io, os, term, term/tui, time, threads, sync, and reflect package sources. Ocean is in development; some syntax accepted by the parser may still be unsupported by later compilation stages. Use ocean check to verify that an example can be compiled and linked by your compiler.