Compiler & CLI
Build native executables, inspect LLVM, and understand the build cache.
Run unit tests#
ocean test runs Test functions accepting *testing.T from files ending in _test.oc. Internal tests share private declarations; external <package_name>_test files import only the public API. Ordinary build and run commands exclude test files. The check command and build --check validate same-package and external test files in the selected package without executing them. Dependency test files remain excluded. See the unit testing guide for subtests, fatal failures, cleanup, tang reports, JSON, and saved results.
ocean test .
ocean test . --json
ocean test . --outfile results.txt --jsonfile results.jsonl
Everyday commands#
The executable names ocean and ocean-c accept the same commands and options; the examples use ocean. A location can be a file or directory. A file selects its containing package. Non-main packages build into native library artifacts and cannot be run directly. On Windows these are indexed COFF archives, including outputs named .o; keep llvm-ar on PATH with Clang. Unix and Wasm use relocatable objects.
Use check for validation, run for a development execution, and build when you want a persistent output artifact. All three operate on a package and its imports. Passing main.oc is a convenient way to locate that package; it does not exclude other ordinary .oc files in the directory. Files ending in _test.oc are always excluded from build, run, and check; use ocean test to compile and execute them.
Use --static (short form -s) with build or run to statically link the executable, including the temporary executable used by run. This passes -static to Clang and requires host support and static system libraries, including static libffi when needed. Missing static libraries or unsupported targets cause a linker error. Static linking is rejected for non-main packages and cannot be combined with check, --check, or --emit-llvm. When eligible cached object files already exist, Ocean reuses them and performs the link step again with static linking enabled. Use -- to pass a literal --static or -s argument to a running program.
Native builds emit separate LLVM modules directly for each source package and shared program support. Packages compile all ordinary functions so a cached object can serve different callers. Executable linking discards unused functions and data using function/data sections. Library builds preserve callable functions for downstream users. The --emit-llvm option retains a single merged inspection file containing reachable executable functions.
Without -o, an executable uses the package directory’s name as its output name. A non-main package produces an object file instead. Choosing an explicit output path is useful in scripts because it avoids depending on a directory’s current name.
ocean check .
ocean run .
ocean run ./main.oc argument
ocean run . -- --static
ocean build . -o application
ocean build --static . -o application
ocean run -s .
ocean build ./library -o library.o
The -- separator makes the boundary between compiler options and program arguments clear. For a directly built executable, invoke its output path through the shell. run rejects a package that is not an executable root named main.
LLVM and validation#
--emit-llvm writes textual LLVM IR, defaulting to a.ll if no output is specified. check validates syntax, semantics, backend lowering, LLVM verification, and native linking. It may compile and link temporary files to validate the build, but does not leave an executable at your requested output path or execute your program.
Textual LLVM output is useful when inspecting how an Ocean construct is lowered or when working with a separate native compilation step. It contains compiler-generated code rather than the original source.
Checking is broader than parsing. The compiler resolves imported packages, performs semantic validation, lowers the program, verifies the generated LLVM, and checks native linking. A successful check therefore validates the implemented backend path, but does not test runtime behavior or execute application logic.
ocean build --emit-llvm . -o application.ll
ocean build --check .
ocean check ./main.oc
Both checking forms avoid publishing an executable. They can still report errors from the native toolchain, including unresolved external functions. Temporary artifacts used during validation are removed after the check.
Run behavior#
run builds in a private temporary directory and executes with the current working directory and inherited standard streams. Normal arguments and unrecognized flags after the location are forwarded to the program. Ocean compiler flags are parsed by Ocean until --; everything after -- is passed literally to the program. The executable’s exit status is returned, and temporary artifacts are removed afterward.
The temporary build location is separate from the process working directory. Relative paths used by the running program are still interpreted from the directory where you invoked Ocean, and terminal input and output are inherited. This makes a development run behave much like invoking a built executable yourself.
Pass arguments directly after the program location: ocean run . arg1 arg2. Unrecognized flags after the location are also forwarded. Ocean recognizes -o, --emit-llvm, and --check anywhere before --, even after normal program arguments; these build-only options are incompatible with run. Use -- to pass matching names to the program, for example ocean run . arg1 -- -o output --check. Ocean returns the program’s exit status to the invoking shell. A func main() int result becomes that status; a no-result main normally exits with zero.
The temporary executable and directory are removed after execution, including runtime failures and handled interrupts. Use build instead when another tool needs to inspect or invoke the resulting file later.
Build caching#
With caching enabled, native builds cache compiled objects per source package and shared program support in ~/.cache/ocean-build. Native cache keys hash source contents and paths, transitive dependency sources, compiler and native toolchain identity, host, working directory, and environment. Generated LLVM is not an input to native cache lookup. Dependency invalidation is conservative: changing a dependency implementation rebuilds its importers.
Cache lookup happens before backend emission. When all objects and link metadata are cached, Ocean skips LLVM generation and native compilation, then relinks against current system libraries. On misses, the backend emits package LLVM files directly; there is no merged-file splitter. Unchanged package objects can be reused when an application starts calling additional package functions. Rebuilding shared support still lowers the graph to collect type and runtime requirements from all packages. Support uses a whole-program source key because it owns globals, startup, concrete specializations, and type-dependent runtime dispatch.
The --emit-llvm inspection output has a separate source-keyed cache. Parsing and semantic checks still run. Native threading mode is part of package cache keys, so cached functions retain the correct cancellation checkpoints. Threading link metadata persists with the cached support object, including its native runtime; POSIX -pthread is added only when needed. The check command validates direct package modules in temporary files. Output filenames, link-only --static, and application arguments do not invalidate native objects. When caching is disabled with OCEAN_BUILD_CACHE=off or cannot be initialized, native builds use a single LLVM module and one Clang invocation. Executables lower only reachable functions; libraries retain ordinary functions for downstream callers. An empty usable cache still compiles and stores package objects. Individual missing or corrupt artifacts are treated as cache misses.
ocean clean --cache removes the build cache without removing downloaded modules.
ocean clean --cache
# Shell environment overrides:
OCEAN_BUILD_CACHE=off ocean build .
OCEAN_BUILD_CACHE=/path/to/cache ocean build .
Use OCEAN_BUILD_CACHE=off to compare behavior without cached artifacts or when investigating a build problem. A custom cache path can keep generated data in a location appropriate to your environment. Disabled or uninitializable caches fall back to single-module compilation; an empty usable cache still populates package objects.
Diagnostics#
Errors and warnings include a filename, line, column, excerpt, and caret. Terminal output uses color; redirected output is plain. NO_COLOR disables color, and CLICOLOR_FORCE=1 forces it. Build failures preserve previous output files.
Read diagnostics from the first reported location and use the excerpt to identify the expression involved. A syntax error can cause several later messages, so fixing the earliest issue and checking again is often more useful than addressing every downstream message separately. Source paths are relative to the compiler’s working directory where possible.
Warnings do not prevent a successful compilation. One example is a value-returning function that reaches its end and implicitly returns a zero value. Prefer an explicit return so the intended behavior is visible. Native compiler and linker failures also make the build unsuccessful.
If a previous output file exists, a failed build preserves it. Be careful when running an old executable after a failed rebuild: its presence is not evidence that the latest source compiled successfully.