Packages & modules
Organize source files and share code across local and external packages.
A directory is a package#
All ordinary .oc files in a directory belong to the same package and must declare the same name. Files ending in _test.oc are excluded from normal builds. During ocean test, same-package tests can use private declarations, and a separate <package_name>_test package can share the directory for public API tests. Functions, types, and globals are shared across those files. An import is available only in the file that declares it, even though top-level functions, types, and variables are shared across files in the package. Only the root package main gets an executable entry point.
Package membership comes from the source directory and declaration, not the source filename. Splitting a large program into several .oc files in one directory does not require imports between those files. Their global-level declarations share the package scope, while local declarations still follow ordinary lexical scope.
Imports are different: each file must import the packages whose qualified names it uses. Importing io in main.oc does not make io available in a sibling source file. Extern declarations are also file-scoped and must be repeated in each file that calls them.
package main;
import "io";
func main() {
io.Println("One directory, one package.");
}
This file belongs to the executable package main. A sibling file beginning with package main; can declare helpers that main calls directly. A sibling file declaring a different package would cause a package-name error.
Initialize a module#
A module root contains ocean.mod. Its subdirectories are separate packages. ocean mod init uses the supplied module name or the current directory’s name; it preserves an existing module file.
The module name supplies a stable prefix for imports inside the project and for code importing it externally. It usually resembles a repository path. One module can contain several packages. Each directory containing Ocean source is a package, while the root ocean.mod gives those packages a common import prefix. Subpackages do not need separate module files.
Run initialization from the directory you want to use as the root. The command creates ocean.mod containing the chosen module name and an ocean 0.1 directive. With no explicit name, the current directory’s name is used. An existing module file is preserved rather than overwritten.
ocean mod init github.com/yourname/project
The example path is illustrative; replace it with the name of your project. After initialization, a helper subdirectory is a separate package that can be imported using the module name followed by /helper.
Import packages#
Import qualifiers default to the declared package name, except for packages at a module root, which use the final component of the module import path regardless of their declaration. For example, importing example.com/calculator binds calculator, even if the root declares package main;. Aliases use as and override this default. Names beginning with a Unicode uppercase letter are exported; lowercase declarations are private to their package. Import cycles and mixed package names are errors, except for the separate external test package allowed in _test.oc files.
The import path identifies where a package is found; the qualifier used in expressions normally comes from that package’s package declaration. An alias changes the local qualifier for this file, which is useful when two imports would otherwise have the same package name.
Exporting is name-based. A capitalized function such as Answer is available to importers, while lowercase helpers remain accessible only inside their own package. The rule also applies to types, global variables, receiver methods, aliases, and interfaces. Dot imports expose exported names directly; blank imports do not introduce a normal qualifier.
import "github.com/yourname/project/helper";
import "github.com/example/collections/list" as lists;
// Inside a function:
answer := helper.Answer();
In this illustrative module layout, the first import supplies helper.Answer(). The second package is bound as lists regardless of its usual qualifier. Each referenced package must actually exist and declare the exported names you call.
Dependencies and replacements#
require selects a Git tag or branch. replace redirects a module requirement to a local directory or a different module/version without changing the import paths written in your source. A local replacement needs its own ocean.mod. External modules use direct Git over HTTPS and are cached.
A requirement records which version of an external module to select. Versions are resolved through Git tags or branches, and module downloads are reused from the module cache. Unlike systems with a module proxy, Ocean fetches repository content directly over HTTPS.
A local replacement is useful while developing two modules together. It keeps the logical import path unchanged while directing resolution to a checkout on disk. That checkout must have its own module declaration so the package graph can be resolved consistently. Single-line and parenthesized directive groups are accepted.
module github.com/yourname/project
ocean 0.1
require github.com/example/collections v1.2.3
replace github.com/example/collections => ../collections
The example dependency and version are placeholders. The replacement makes that dependency resolve to the sibling collections checkout. Removing a build cache entry will not change which external module sources are available in the independent module download cache.
Initialization#
Imported packages initialize before importers. Within a package, files are sorted by filename and global initializers execute in declaration order. Globals are default-initialized first, so a forward reference may observe a default value. Owned contents of global arrays, strings, and maps remain available for the program’s lifetime and are released at process shutdown.
Default initialization happens before user initializers execute. This means a global referenced before its initializer runs has a defined default, rather than causing the compiler to reorder arbitrary expressions to satisfy the reference. Explicit types are useful for forward-referenced globals because they make the intended storage type unambiguous.
Keep global initialization simple and avoid relying on surprising file-order dependencies. Imported packages finish initializing before their importers. Within one package, filename order and then declaration order determine execution. Global collections own their copies for the program’s lifetime. A function using a global collection does not borrow the temporary storage used while its initializer ran.
Select native and Wasm source files#
The compiler selects *_native.oc and *_native_test.oc only on native targets, and *_wasm.oc and *_wasm_test.oc only with OCOS=js OCARCH=wasm. Selection happens before parsing/import resolution, including editor overlays. Other .oc files are shared. These suffixes separate native transports and synchronization from Wasm host adapters; they do not select individual native OS/architecture pairs.