Standard library repository
Understand the ocean-src layout, its compiler integration, and how to verify library changes.
Repository layout#
ocean-src is the standard-library source root. Each package is a directory beneath that root and is imported by its directory path: import "io"; resolves the io directory under the configured library root. Source files begin with their package declaration. The current repository is small; it does not contain a general-purpose collection of packages borrowed from another language.
| Path | Contents |
|---|---|
README.md | Library overview, installation relationship, and shared I/O conventions. |
io/ | Printing, formatting, round-trip float text, number parsing, and buffered scanning. |
os/ | Arguments, process exit, standard streams, file modes, native reads/writes, and seeking. |
os/exec/ | POSIX process execution and output capture on Linux x86-64. |
encoding/json/ | Dynamic JSON decoding and scalar, array, object, and struct encoding. |
net/http/ | Blocking plain HTTP/1.1 client for 64-bit Linux. |
math/, mem/ | Binary64 mathematics and overlapping raw byte copies. |
term/, term/tui/ | Terminal utilities and a model/update/view application framework. |
time/ | Nanosecond duration units and native Sleep. |
threads/, sync/ | Native thread lifecycle, cancellation, mutexes, and wait groups. |
reflect/ | Struct and enum snapshot APIs backed by restricted compiler primitives. |
testing/, testing/internal/display/ | Test API and the compiler’s live test-report frontend. |
How packages connect to the compiler#
io implements printing and formatting in Ocean, including reflected struct and enum formatting, portable float conversion, and platform assembly for stdout. os provides process arguments, standard streams, native File values, FileMode, Open, and Close; application code calls os.Args() for arguments. reflect exposes Field, Fields, IsStruct, IsEnum, and EnumVariant. threads and sync wrap native thread lifecycle and synchronization support. os.Exit immediately terminates the whole process. The compiler embeds the cross-platform C runtime, emits function-value and thread-return bridges, and inserts cancellation checkpoints when native threading is used.
Reflection primitives are available only to the actual reflect package under the configured standard-library root. A project-local package with the same name does not gain access. If a library change depends on a new compiler hook or native calling convention, update and test the compiler alongside the library. Merely editing the .oc source cannot add support that the compiler does not implement.
Work directly from the checkout#
Clone the library beside the compiler and point OCEAN_SRC at its absolute path. Run these commands from the directory containing both repositories, after building the compiler. Replace /path/to/example with a package that exercises your change.
git clone https://github.com/junglehornet/ocean-src.git
# With a built sibling ocean-c checkout:
OCEAN_SRC="$PWD/ocean-src" ./ocean-c/build/ocean check /path/to/example
OCEAN_SRC="$PWD/ocean-src" ./ocean-c/build/ocean run /path/to/example
There is no separate library compilation or npm/CMake build in this repository. Ocean compiles the required library packages with the importing program. For installation, preserve the package directories under the installed src/ root.
Add or change a package#
Keep each package in its own directory and use a matching package declaration. Follow existing export conventions: public names start with an uppercase letter. Add source files to the package directory when splitting an implementation.
Exercise new behavior from a small importing program. Run Ocean unit tests with OCEAN_SRC=/absolute/path/to/ocean-src ocean test /absolute/path/to/ocean-src/... --notty; HTTP tests require loopback sockets. Native Python integration harnesses also live under term/tests, term/tui/tests, threads/tests, and time/tests; set OCEAN to the matching compiler executable when running them. For compiler-integrated behavior, add regression coverage to the compiler repository: tests/io_backend_test.py, tests/os_args_test.py, and tests/reflect_test.py cover the current packages. Run the relevant CTest suites and update the corresponding reference page in this website. Preserve the documented copy behavior when changing an API. In particular, test whether returned strings, arrays, maps, and boxed values remain valid after local source values leave scope, and whether a reflected snapshot is independent of later changes to the source struct.