Docs/Language guide

Packages & imports

Organize files, import shared code, and understand visibility and method ownership.

One directory, one package#

Every .oc file starts with a package declaration. All Ocean files in a directory must declare the same package. Functions, types, and global variables are shared across those files, including lowercase helpers. Subdirectories are separate packages. Passing a source file to the compiler selects its entire directory. Only a root package named main gets an executable entry point.

The “root package” is the package you select on the command line. Selecting an imported helper package does not automatically build another main package elsewhere in the module. A module is the project-wide import namespace; each source directory within it is still a separate package.

Ocean
package main;

func main() int {
    return answer();
}

// In helper.oc in the same directory:
// package main;
// func answer() int { return 42; }

Create a module and a package#

Run ocean mod init example.com/app in your project directory. This creates ocean.mod. Save the library below as greeting/greeting.oc, and the importing program as main.oc in the project root. Run ocean check . to validate both packages or ocean run . to execute the program.

Ocean
// greeting/greeting.oc
package greeting;

func Message() string {
    return "Hello from another package";
}

// main.oc
package main;

import "io";
import "example.com/app/greeting";

func main() {
    io.Println(greeting.Message());
}

The module name example.com/app becomes the prefix in "example.com/app/greeting". Because that package is inside the same module, Ocean resolves it to the local greeting directory. Running this example does not require publishing a repository at that address.

Import paths and aliases#

The import path tells Ocean where to find the package directory. The qualifier is the name before a dot in an expression such as greeting.Message(). By default, that qualifier comes from the imported source’s package greeting; declaration, which need not be the last component of the import path. A package at a module root instead uses the final component of the module import path, regardless of its package declaration: import "calculator"; binds calculator, even for package main;. Module-relative paths such as "greeting" are also accepted. Standard-library imports such as "io" resolve under the installed source directory, which OCEAN_SRC can override. External modules resolve through the module configuration and Git cache. An as alias changes the qualifier for the current file. Each file must declare the imports it uses.

Ocean
package main;

import "example.com/app/greeting" as hello;
import "io";

func main() {
    io.Println(hello.Message());
}

After the as hello alias, this file calls the exported function as hello.Message(). The alias changes how this file refers to the package; it does not rename the package in its own source or in other importing files.

Exports, dot imports, and blank imports#

Names beginning with an uppercase letter are exported. Lowercase declarations remain private to their package. This applies to functions, types, globals, receiver methods, interfaces, aliases, and enum types and variants. Extern declarations are file-scoped and are not exported through imports. A dot import introduces exported names without a qualifier; collisions can make a reference ambiguous. A blank import, written with _, loads and initializes the package but does not introduce a qualifier or any directly callable names into this file.

Ocean
import . "example.com/app/greeting";
import _ "example.com/app/setup";

// Inside a function, the dot import allows:
message := Message();

Methods belong to the defining package#

A receiver method must be declared in the package that defines its receiver type. It may be in a different file within that package. You cannot add methods to imported types, including types brought into scope by dot imports or local aliases of imported types. For example, type Local = imported.Type is an alias of the imported type and cannot be used to add local methods. type Local imported.Type creates a distinct type defined in the current package; methods for that new type may be declared locally.

Ocean
// In the greeting package:
struct Greeting { text string; }

func (message Greeting) Text() string {
    return message.text;
}

Initialization and package errors#

Imported packages initialize before their importers. Within a package, files are sorted by filename and globals initialize in declaration order, after all globals have received their type’s default value. If an initializer reads a global whose explicit initializer has not run yet, it can see that default rather than the value assigned later. Import cycles, conflicting package declarations, ambiguous imported names, and access to private declarations are errors.