Building & compiler architecture
Build a development compiler, find each compilation stage, and choose the right tests for a change.
Check out the sources#
Install Git, CMake 4.2 or newer, a C23-capable C compiler, Clang, and libffi development headers and libraries. Python 3 is required when tests are enabled, as they are by default. CMake selects Clang unless you choose another C compiler.
Clone the two repositories into sibling directories. The standard library is Ocean source loaded by the compiler; it does not have a separate native build.
git clone https://github.com/junglehornet/ocean-c.git
git clone https://github.com/junglehornet/ocean-src.git
cd ocean-c
Configure and build#
Run these commands from ocean-c. An out-of-source Debug build keeps generated files separate and provides debugging information. OCEAN_STANDARD_LIBRARY_SOURCE selects the source tree copied during installation; OCEAN_SRC selects the library used while running the compiler.
The C compiler builds Ocean itself. Ocean emits textual LLVM IR and invokes Clang to produce and link native code. LLVM development libraries are not required; libffi supports native calls and boxed runtime values. It is a dependency of the compiler build even though LLVM development libraries are not.
cmake -S . -B build -DCMAKE_BUILD_TYPE=Debug -DBUILD_TESTING=ON -DOCEAN_STANDARD_LIBRARY_SOURCE="../ocean-src"
cmake --build build --parallel
ctest --test-dir build --output-on-failure
The build produces build/ocean-c and an ocean copy beside it. Rebuild after editing C sources. To change C compilers, configure a fresh build directory with -DCMAKE_C_COMPILER=... rather than reusing an incompatible CMake cache.
Run against your library checkout#
An uninstalled executable in build/ will not automatically find the sibling ocean-src checkout. From the compiler repository, set OCEAN_SRC to that checkout and use an absolute path to your example package. A check validates the package graph, backend output, and native link without executing the program.
# Shell
OCEAN_SRC="$PWD/../ocean-src" ./build/ocean check /path/to/example
OCEAN_SRC="$PWD/../ocean-src" ./build/ocean run /path/to/example
To test installation, configure with -DCMAKE_INSTALL_PREFIX="$HOME/.local/ocean", rebuild, and run cmake --install build. The prefix receives bin/ocean and src/ containing library sources. Add its bin/ directory to PATH. If testing cache behavior is not your goal, OCEAN_BUILD_CACHE=off can help isolate a compiler change.
Follow the compilation pipeline#
Compiler implementation files live at the repository root. Start at main.c for command dispatch and tool invocation. Package loading brings together a graph of source files and imports; the scanner turns source text into tokens, and the parser turns those tokens into the abstract syntax tree (AST); semantic analysis resolves names and types; the backend lowers the program to LLVM IR. Clang handles native compilation and linking.
| Files | Responsibility |
|---|---|
main.c | CLI commands, build/check/run orchestration, and native tool execution. |
package.c, package.h | Package and module loading, import resolution, and standard-library lookup. |
scanner.c, token.c | Lexing source text and representing tokens. |
parser.c, ast.c and their headers | Parsing declarations and expressions, syntax structures, and AST utilities. |
semantic.c, semantic.h | Bindings, type resolution, and semantic diagnostics. |
backend.c, backend.h | LLVM emission, runtime helpers, and value ownership/cleanup lowering. |
llvm_packages.c | Splitting emitted LLVM into package units. |
runtime_threads.c, backend_threads.inc | POSIX/Win32 threads and synchronization, C ABI bridges, and cooperative cancellation. |
build_cache.c | Generated IR and native-object caching. |
lsp.c, lsp_semantic.inc | LSP transport, document state, diagnostics, and semantic editor features. |
dynarray.c, c-hashmap/, shared headers | Supporting collections, type representations, source paths, and diagnostics. |
Choose tests for the change#
CMakeLists.txt defines the compiler sources and registers the CTest suites. tests/ contains C unit tests and Python integration tests. Parser suites inspect syntax directly; backend tests compile Ocean fixtures, inspect output, and run native programs. Other integration suites exercise import resolution, cache reuse, reflection behavior, and editor requests, so choose the suite for the behavior your change affects rather than only the file you edited.
Run a focused suite while iterating, then run the full suite before submitting. A parser accepting a construct does not prove semantic or native support. A language change may need scanner/parser coverage, semantic rejection cases, runtime behavior, editor checks, and updated docs.
ctest --test-dir build -R parser --output-on-failure
ctest --test-dir build --output-on-failure
Read tests/README.md for suite conventions and tests/pending/README.md plus tests/pending/features.json for tracked limitations. Pending cases can be skipped; a skip is not proof that a feature works. Include a focused regression for a bug and describe which tests you ran.