Docs/Start here

Get started with Ocean

Download and run the Ocean installer, or build from source, then write, check, and run your first program.

Download the Ocean installer#

Open the Ocean releases page using the link below. Choose a published release, expand its Assets list, and download the ocean-installer_<tag>_<arch>-<os> archive that matches your computer. Nightly prereleases use tags such as nightly-2026.11.15.

Use aarch64 for Apple silicon and other ARM64 computers, or x86_64 for Intel/AMD 64-bit computers. Linux also supports riscv64. Download the installer archive, rather than the compiler-only ocean-c asset or GitHub’s Source code archives.

Extract the archive into a folder you can open in your terminal. Linux and macOS installers are in .tar archives; Windows also offers .zip archives you can extract in File Explorer. The extracted file is ocean-installer on Linux/macOS or ocean-installer.exe on Windows. Install Git first if it is not already available, then run the extracted installer:

Terminal
# Shell (Linux and macOS, after extracting)
./ocean-installer

# Windows PowerShell (after extracting)
.\ocean-installer.exe

Follow the prompts to select a release (latest for stable or latest-nightly for a nightly), an installation directory, dependencies, and PATH configuration. The installer downloads the compiler and its matching standard-library sources. Open a new terminal when it finishes and run ocean --version to confirm the installation. If you used the installer, continue at “Write your first program”; the source-build instructions below are an alternative.

Code with an agent skill#

The compiler repository on GitHub includes an Ocean agent skill covering current syntax, tooling, packages, modules, and the build system. Download the latest SKILL.md from the main branch and save it as ocean/SKILL.md in your coding agent’s skills directory. Use your agent’s skill installation instructions to choose that directory.

Get the source#

Ocean can be installed from native release assets or built from source. Nightlies use matching nightly-YYYY.MM.DD tags for the compiler and standard library, taken from their main branches. Releases are checked at midnight UTC: changes in either repository trigger a build, while unchanged sources are rebuilt after 30 days. There is no nightly branch. Each nightly is named for the UTC day that just ended; for example, the December 1 run uses November 30. Use matching tags when installing a nightly compiler and library. Clone the compiler repository, ocean-c, and the standard-library repository, ocean-src, into the same parent directory. This makes them sibling directories, so the compiler’s build configuration can find the library at ../ocean-src. Git is also used when Ocean downloads external modules.

The standard library consists of .oc source files. Keep its package directories intact; Ocean compiles the packages your program imports when it builds that program. You do not need to build the library separately.

The commands below create both checkouts and then enter ocean-c. The installation section explains how CMake copies the compiler into <prefix>/bin and the library into <prefix>/src. For a manual system-wide installation, /usr/local/lib/ocean can serve as that prefix: place the executable in /usr/local/lib/ocean/bin, copy the library source tree into /usr/local/lib/ocean/src, and add the bin directory to PATH. The compiler normally finds the library relative to its own executable, not relative to your program’s working directory.

Terminal
git clone https://github.com/junglehornet/ocean-c.git
git clone https://github.com/junglehornet/ocean-src.git
cd ocean-c

The remaining build commands run inside ocean-c. Once Ocean is installed, your own programs can live in any other directory; they do not need to be placed inside either source repository.

Build the compiler#

You need CMake 4.2 or newer, a C23-capable C compiler, libffi development headers and libraries, and Clang on your PATH. Python 3 is also required for the test suite, which is enabled by default. Run these commands from your Ocean compiler checkout. The compiler generates textual LLVM IR and uses Clang to produce native code; LLVM development libraries are not required.

CMake configures the build, and the C compiler builds Ocean itself. Clang has a separate job: it compiles the LLVM output of your Ocean programs and links their native executables. Make sure both your C compiler and Clang are installed, even if you already have one of them.

The build directory holds generated build files and compiler binaries. Keeping those files separate from the source makes it easier to rebuild or change configuration later. The final command runs the compiler’s test suite and reports any failures.

Terminal
cmake -S . -B build
cmake --build build
ctest --test-dir build --output-on-failure

After a successful build, build/ocean is available directly from this checkout. If CMake reports missing libffi headers or libraries, install your operating system’s libffi development package and configure the build again. Package names and installation commands depend on your system.

Install Ocean and its library#

There are two settings for the standard library, used at different times. OCEAN_STANDARD_LIBRARY_SOURCE is a CMake setting: it chooses which library source directory to copy during installation and defaults to the sibling ../ocean-src checkout. OCEAN_SRC is an environment variable: it tells a running compiler which library source directory to use instead of its installed copy.

An installation prefix is the parent directory of the installed bin and src directories. For example, a prefix of $HOME/.local puts Ocean in $HOME/.local/bin/ocean and library packages in $HOME/.local/src. Without OCEAN_SRC, the compiler finds ../src relative to the directory containing its executable. Choose a prefix you can write to and add its bin directory to PATH.

Installation copies the executable and standard-library sources into a common prefix. The compiler normally looks for library packages relative to its own executable, so using the installed layout avoids setting a library path for every command. The example uses a user-owned prefix and does not require a system-wide installation. A system-wide installation can use /usr/local/lib/ocean, giving /usr/local/lib/ocean/bin and /usr/local/lib/ocean/src.

Replace /path/to/ocean-src with the absolute path to your standard-library checkout. If you cloned both repositories into the same parent directory, CMake already defaults to ../ocean-src; no rename is needed. However, spelling it out makes the relationship explicit.

Terminal
cmake -S . -B build -DCMAKE_INSTALL_PREFIX="$HOME/.local" \
  -DOCEAN_STANDARD_LIBRARY_SOURCE=/path/to/ocean-src
cmake --build build
cmake --install build
export PATH="$HOME/.local/bin:$PATH"

The export command affects the current shell. To make it permanent, add the equivalent PATH setting to your shell configuration. You can also run the installed compiler using its full path. OCEAN_SRC is useful when testing changes in a separate standard-library checkout.

Write your first program#

Create a new directory, run ocean mod init example.com/hello there to create its ocean.mod module file, and save the following as main.oc. Every Ocean file starts with a package declaration. A root package named main can build into an executable.

Use a directory containing only this example while you are getting started. Ocean compiles packages rather than isolated files, so an unrelated ordinary .oc file in the same directory will also be part of the program. Files ending in _test.oc are reserved for ocean test and excluded from normal builds. You can call the new directory hello; the source filename itself does not determine the package name.

package main; identifies an executable package. import "io"; makes the standard output functions available in this file. When the executable starts, Ocean calls main, whose body prints the message and then finishes.

Ocean
package main;

import "io";

func main() {
    io.Println("Hello, Ocean!");
}

Save the file before running the next commands. The string is enclosed in double quotes, the call ends with a semicolon, and the closing brace ends the function body. This program should print Hello, Ocean! followed by a newline.

Check, run, build#

Run these commands inside your program directory. check validates the package and its imports without executing your program. run builds and executes a temporary executable. build creates a native executable you can keep.

Start with ocean check . when you want feedback without running code. It checks the complete package graph, including same-package and external _test.oc files in the selected package, and verifies that native code can be produced and linked. Tests are validated without being executed; imported dependencies’ test files remain excluded. This means a missing native toolchain can fail a check even when the Ocean syntax is valid.

ocean run . is convenient during development because it removes the temporary executable afterward. Use ocean build when you want an executable to run again, distribute, or inspect separately. The optional -o option chooses its output filename, which will default to the selected package directory’s name.

Terminal
ocean check .
ocean run .
ocean build . -o hello
./hello

The dot refers to your current directory. The last command runs the executable produced by the preceding build. If io cannot be resolved, check that the standard library was installed alongside Ocean or that OCEAN_SRC points to the library source directory.

Read the syntax#

Statements generally end with a semicolon unless they end in a block. An ordinary return statement may also omit its semicolon when the next token is a closing brace (}). Braces enclose function bodies and control-flow blocks. In a declaration, the name comes before its type. Use := when the compiler can infer the type.

For example, value int declares an integer parameter, and the int following the closing parenthesis declares the result type. A call to twice must supply a compatible value, and its result is itself an integer. Local type inference saves you from repeating that type in answer := twice(21);.

Ocean still checks inferred variables statically. Once a variable has an inferred type, assigning a different kind of value does not change that type. Use explicit type annotations in public function signatures or wherever a declared type makes the code easier to understand.

Ocean
func twice(value int) int {
    return value * 2;
}

// Inside main:
answer := twice(21);
io.Println(answer);

Place the function declaration outside main, then put the final two statements inside main. The call passes 21, the function multiplies it by two, and the printed result is 42. The language guide covers these rules in more detail.